yaVDR-Dokumentation verbessern: Wer macht mit?

Quote from hepi

1) Wie würdest Du gemeinschaftliches paralleles Arbeiten mehrerer Autoren an einem Text mit AsciiDoc ermöglichen?

Da man über Datei-includes arbeiten kann, lässt sich die Dokumentation in einzelne Dateien splitten, die ggf. mit einem kollorabotivem Editor wie etherpad gemeinsam bearbeitbar sind (und/oder man nimmt ein Versionsverwaltungssystem wie git, dann kann man für Entwicklungsversionen von yaVDR jeweils forken und die Änderungen gegenüber dem Vorgänger dokumentieren).

*Zukunftstraum* Falls man mal soweit kommt, dass eine praktisch vollständige Dokumentation zu yaVDR vorliegt, könnte man abhängig vom aktiven Frontend, den aktiven Plugins und der Konfiguration über das Template-System ein individuelles Handbuch für eine yaVDR-Installation generieren lassen, inkl. Links aus dem Dokument heraus z.B. auf die zur Anleitung passende Seite des Webinterface.

Quote from hepi

Die Syntax scheint sich m. E. von Mediawiki Markup auf den ersten Blick kaum zu unterscheiden. Wo siehst Du die Vorteile gegenüber Mediawiki Markup?

Die Syntax ist in der Tat relativ ähnlich, evtl. erleichtert das den Austausch mit dem VDR-Wiki. Mir hat vor allem gefallen, dass man relativ bequem zu praktisch jedem gängigen Ausgabe-Format kommt, kein PHP und Webserver braucht und die Exporte in die unterschiedlichen Dateiformate und Sprachanpassungen gut Skripten kann.

Da sich yaVDR zu einer Distribution mit einem sehr gut strukturierten Konfigurationssystem entwickelt, denke ich man kann den Nutzern den Einstieg deutlich erleichtern, wenn man versucht eine gute durchgängige Dokumentation für ein Release zu erstellen (natürlich geht das nicht von jetzt auf gleich), die nicht von den unterschiedlich aktuellen Artikeln im Wiki abhängt (die oft auch nur z.T. auf yaVDR zutreffen) und ein Einlesen über viele viele Einzelartikel erfordert (außerdem kann man dann endlich mal ein deutliches RTFM hier im Forum loslassen ).

Ich werde mal weiter damit spielen, ist auf jeden Fall ganz nett und für die meisten Anwendungsfälle eine brauchbare Markup Language.

Egal ob Wiki oder AsciiDoc: Das Grundproblem ist, Autoren zu finden, die bereit sind zu schreiben und zu kooperieren - und die koordiniert arbeiten. Es gibt wie hier im Thread beschrieben auch Autoren, die Lust haben zu schreiben, aber nicht die Lust oder Zeit haben, mit anderen Autoren zu kooperieren.

Wenn die Doku auch eine Art Hardwaredatenbank enthalten soll (DVB-Geräte, Fernbedienungen, Mainboards), wo jeder User Infos zu seiner Hardware hinterlegen kann, hat meines Erachtens das (Semantic) Mediawiki deutliche Vorteile gegenüber dem AsciiDoc.

Jeder, der Mediawiki Markup lernt, kann dieses Wissen an vielen Stellen im Web nutzen: Im VDR-Wiki, in der Wikipedia, etc, im LinuxTV.org-Wiki. Deshalb bin ich nach wie vor Anhänger einer Wiki-Lösung.

Wenn Du es aber schaffst, mit AsciiDoc die Autoren hinterm Ofen hervorzuholen, die nur gähnen, wenn auf's Wiki verwiesen wird, dann Hut ab. Viel Erfolg!

Gruß
hepi

Um es nochmal zu destillieren, für alle die die letzten sechs Seiten dieses Threads nicht gelesen haben.

Ich wünsche mir nichts sehnlicher als tolle und ausführliche yaVDR-Doku - genau wie seahawk.
Ich habe dafür schon ein neues, leeres yaVDR-Wiki eingerichtet und dafür Werbung gemacht, weil ich von den Semantic-Extensions begeistert war. Genau die gleiche Begeisterung hat jetzt seahawk für sein AsciiDoc.

Weil alles weitere dann aber nicht klappte (Autoren finden, die regelmäßig schreiben), und die Semantic-Extensions auf allgemeines Desinteresse gestoßen sind (verständlich, weil hier im Portal von 27.300 Usern nur 15 im VDR-Wiki Hand anlegen), bin ich dazu übergegangen, einfach den yaVDR-Content im VDR-Wiki zu ergänzen, umzuschreiben und zu aktualisieren.

Seitdem haben wir meiner Meinung nach zumindest viel weniger sich wiederholende Einsteigerfragen hier im Portal, solange die Fragen in der FAQ beantwortet werden.

Gruß
hepi

Wenn jemand keine Lust auf Auszeichnungs-Sprachen hat, kann er mit auch gerne normalen Text (ggf. + Bilder) schicken, das Formatieren ist das geringste Problem.

Die Wiki-Inhalte lassen sich relativ leicht importieren, für yaVDR 0.4 ist noch einiges dabei, das aussortiert werden muss. Aber der css-Stil gefällt mir http://db.tt/FpuC28c
BTW: Da das File in meinem Dropbox-Ordner liegt, zeigt es immer auf die aktuell durch mein Export-Skript erstellte Version. Ersetzt man das die Datei-Erweiterung .html durch .txt sieht man die Quelldatei (dort sind auch die Verweise auf die anderen Quelldateien zu finden).

Quote from seahawk1986

Die Wiki-Inhalte lassen sich relativ leicht importieren, für yaVDR 0.4 ist noch einiges dabei, das aussortiert werden muss. Aber der css-Stil gefällt mir http://db.tt/FpuC28c

Seahawk, danke für Dein Engagement und Deinen Prototypen! Er sieht hübsch aus, aber ich sehe noch immer keine Vorteile gegenüber einem Wiki. Ein Wiki kann per CSS-Regeln / Themes auch im Design komplett aufgehübscht werden, um nicht altbacken zu erscheinen.

Der Knackpunkt ist für mich: Wenn ein Autor seine Beiträge als Plaintext in ein Git-Repo committen soll, schränkt das meiner Meinung nach den Nutzerkreis auf Entwickler ein, die sich mit Git auskennen. Das ist dann meiner Ansicht nach ein komplizierterer Workflow als im Wiki.

Ich würde AsciiDoc in unserem Zusammenhang als nützlich ansehen für eine automatische PDF-Generierung von Wiki-Content, wenn es das kann. Aber ich sehe es nicht als schreibfreundliche Umgebung an.

Vorteil Wiki: Jemand liest eine Seite, entdeckt einen Fehler, macht eine Änderung, die Änderung ist sofort da.

Das yaVDR-Wiki, das ich zum Testen eingerichtet habe, ist hier zu finden:
http://wiki.yavdr.com/de/Hauptseite

Meine Apelle, das VDR-Wiki auf einen neuen Softwarestand + Semantic-Plugins zu bringen, sind hier zu finden:
Demo: Strukturierte Wiki-Doku mit Semantic Mediawiki

In unserem team-internen Forum gibt es einen eigenen Bereich namens "Doku-Initiative 2011", in das ich alle Leute eingeladen habe, die hier im Thread ernsthaftes Interesse geäußert haben, die Doku zu verbessern. Die Diskussion dort ist aber eingeschlafen.

Wenn wir uns auf Mediawiki einigen könnten als Doku-Basis: Ich brauche dort tatsächlich viel technische Unterstützung, zum Beispiel beim Ausloten der Möglichkeiten und Grenzen eines zweisprachigen Wikis (Englisch und Deutsch parallel in einem Wiki).

Gruß
hepi

Ok, durch mein Praktikum habe ich im März/April das yaVDR-Wiki-Projekt wohl verpasst, danke für die Erinnerung, Unterforum für Verschiedenes ist dein Post dazu ja leider untergegangen.
Ich schau es mir gerade an - könnte man noch USB-ID bzw. Product-ID (oder sinnvolle udev-Merkmale) in das Formular für DVB-Karten aufnehmen?

Ich finde die Mediawiki-Syntax stellenweise einfach umständlich (die von Ikhaya aus dem UU-Wiki/Forum ist für mich viel eingängiger, aber das Projekt ist ja leider immer noch closed source)

Hallo,
bin dabei. Habe schon einiges im VDR-Wiki (und ubuntuusers) geschrieben.
Englisch ist mir sogar fast lieber (+17 Jahre Arbeitssprache). Mein erster VDR stammt von 2001, damals noch alles selbst kompiliert.

Super, wenn du dich einbringen willst. Hier gab es vor ein paar Monaten mal ein erstes Brainstorming welche Artikel am ehesten fehlen: http://wiki.yavdr.com/de/Startseite

Hi,

Quote from seahawk1986

Ok, durch mein Praktikum habe ich im März/April das yaVDR-Wiki-Projekt wohl verpasst, danke für die Erinnerung, Unterforum für Verschiedenes ist dein Post dazu ja leider untergegangen.

Der Post ist aber nicht in irgendeinem Unterforum von Verschiedenes, sondern im Unterforum "Forum", wo er denke ich auch hingehört. Es gibt hier im VDR-Portal kein Unterforum für Verbesserungen am VDR-Wiki. Viele meiner Gedanken finden sich auch in diesem Thread (den ihr gerade lest), es lohnt sich vielleicht mal den kompletten Thread zu überfliegen, um den Stand der Diskussion zu haben.

Quote from seahawk1986

Ich finde die Mediawiki-Syntax stellenweise einfach umständlich (die von Inkoya aus dem UU-Wiki/Forum ist für mich viel eingängiger, aber das Projekt ist ja leider immer noch closed source)

Sicher, die Syntax von Mediawiki muss man lernen, manches erklärt sich leichter als anderes - Fakt ist: Mediawiki ist sehr verbreitet und durch Wikipedia ein Quasi-Standard. Auch das VDR-Wiki ist doch ein Mediawiki! Aber der Lernaufwand ist nicht besonders hoch, solange man keine riesigen Tabellen bauen will (ich meine die Tabellen, auf die ich auf meiner Semantik-Beispielseite verweise). Ansonsten können wir ruhig auch mal solche Mediawiki-Plugins testen, die einen WYSIWYG-Editor hinzufügen: http://www.mediawiki.org/wiki/WYSIWYG_editor
Anders sieht es aus, wenn es um die Semantik-Extensions geht. Hier ist der Lernaufwand höher, das muss man aber auch nicht allen Autoren abfordern. Es reicht, wenn es nur ein paar wenige Leute können, weil die Autoren dann über semantische Formulare Inhalte eingeben, was sehr einfach für sie ist.

Quote from seahawk1986

Ich schau es mir gerade an - könnte man noch USB-ID bzw. Product-ID (oder sinnvolle udev-Merkmale) in das Formular für DVB-Karten aufnehmen?

Aber natürlich!!! Meine Semantik-Demo ist nur ein unvollständiger Entwurf.

Quote from Dieter

Hallo,
bin dabei. Habe schon einiges im VDR-Wiki (und ubuntuusers) geschrieben.
Englisch ist mir sogar fast lieber (+17 Jahre Arbeitssprache). Mein erster VDR stammt von 2001, damals noch alles selbst kompiliert.

Sehr schön! Ich werde Euch mal in unser internes Doku-Forum einladen.

Gruß
hepi

So, ich habe mal was zu eventlircd und den Templates geschrieben (bzw. in Wiki-Form gebracht), Einstieg am einfachsten über http://wiki.yavdr.com/de/Startseite

Quote from hepi

Sicher, die Syntax von Mediawiki muss man lernen, manches erklärt sich leichter als anderes - Fakt ist: Mediawiki ist sehr verbreitet und durch Wikipedia ein Quasi-Standard. Auch das VDR-Wiki ist doch ein Mediawiki! Aber der Lernaufwand ist nicht besonders hoch, solange man keine riesigen Tabellen bauen will (ich meine die Tabellen, auf die ich auf meiner Semantik-Beispielseite verweise). Ansonsten können wir ruhig auch mal solche Mediawiki-Plugins testen, die einen WYSIWYG-Editor hinzufügen: http://www.mediawiki.org/wiki/WYSIWYG_editor

Gerne, wenn es die Fähigkeiten der Syntax gut abdeckt.

So, da meine Doku schon etwas wächst versuche ich hier noch mal Leute für das Projekt zu gewinnen.
Aktueller Zwischenstand: http://dl.dropbox.com/u/960809/yaVDR_doc.pdf
Wer Teile beitragen will, bitte einfach bei mir melden, ich verwerte (fast) alles, was als Text vorliegt, wenn jemand das in asciidoc-Syntax setzt hab ich natürlich auch nichts dagegen

Quote from seahawk1986

So, da meine Doku schon etwas wächst versuche ich hier noch mal Leute für das Projekt zu gewinnen.
Aktueller Zwischenstand: http://dl.dropbox.com/u/960809/yaVDR_doc.pdf
Wer Teile beitragen will, bitte einfach bei mir melden, ich verwerte (fast) alles, was als Text vorliegt, wenn jemand das in asciidoc-Syntax setzt hab ich natürlich auch nichts dagegen

Seahawk1986, wie Du weißt, respektiere ich Deine Anstrengungen, yaVDR zu dokumentieren. Nach wie vor bin ich aber nicht von asciidoc überzeugt und sehe das als Sackgasse an, wenn mehrer Leute an dem Text schreiben sollen.

Außerdem würde ich Dich bitten zu klären:
1) Unter welcher Lizenz steht Deine Dokumentation? Wer ist der Autor?
2) Bitte stelle klar: Welche Teile sind in der Doku sind von Dir geschrieben und welche Teile hast Du aus dem Wiki kopiert.
3) Welche Autoren haben somit an dem Text mitgearbeitet?

Die Autorenschaft ist über Asciidoc nicht so transparent zu machen so wie das im Wiki möglich ist, wo jede Änderung einen Autoren hat.

Quote from seahawk1986

ich verwerte (fast) alles, was als Text vorliegt,

Was heißt das denn genau in der Praxis?

Ich unterstütze die Idee nicht, das ganze mit Asciidoc zu machen.

Gruß
hepi

Quote from hepi

Nach wie vor bin ich aber nicht von asciidoc überzeugt und sehe das als Sackgasse an, wenn mehrer Leute an dem Text schreiben sollen.

Nachdem diese Situation - wie man an den Versuchen hier im Thread und auch an der Versionsübersicht im Wiki zu den yaVDR-Artikeln sehen kann - eher selten eintritt, behalte ich das erst mal als Format bei.
In den letzten zwei Tagen habe ich das mit Ulf, steffen_b und hoplo auch im IRC diskuTiert, die man gemeinschaftliches Arbeiten ermöglichen könnte. Vorschläge waren Etherpad, Github und Google Docs. Für die beiden letztgenannten ließe sich wohl das Bauen des jeweils aktuellen Standes der Dokumentation automatisieren.
Auch für den Export über asciidoc -> docbook -> MediaWiki gibt es Tools, die einem bei der Überführung in andere Formate wohl Arbeit abnehmen (http://wiki.blender.org/index.php/Meta…DocBook_to_Wiki)

Quote from hepi

Außerdem würde ich Dich bitten zu klären:
1) Unter welcher Lizenz steht Deine Dokumentation? Wer ist der Autor?
2) Bitte stelle klar: Welche Teile sind in der Doku sind von Dir geschrieben und welche Teile hast Du aus dem Wiki kopiert.
3) Welche Autoren haben somit an dem Text mitgearbeitet?

1) Lizenz kann gerne FDL sein, wie auch im VDR-Wiki - oder eine Creative Commons CC-BY-SA 3.0 wenn man den gleichen Trick nimmt, den die Wikipedia angewandt hat (http://de.wikipedia.org/wiki/GFDL#Verw…n_der_Wikipedia). Ist jetzt im Vorwort mit drin. Ich bin bislang der Hauptauthor, das dürfte ähnlich Aussagekräftig sein wie eine IP-Adresse oder ein Pseudonym in der Versionsübersicht eines Artikels im Wiki.
2) Ist klar, das muss eindeutig mit einfließen. Da die FAQ und das Troubleshooting sowieso die am häufigsten veränderten Teile sind und nicht primär auf yaVDR 0.4 ausgerichtet sind, nehme ich sie erst mal raus und verweise direkt auf die Wiki-Artikel. Vielleicht wollen sich du und die anderen, die an den Artikeln mitgewirkt haben ja noch dazu äußern wie sie genannt werden wollen. Ich hatte sie vor allem aufgenommen, um zu sehen wie gut man von Mediawiki-Syntax zu asciidoc kommt.
3) In der jetzt aktualisierten Fassung (gleicher Link wie oben) ich und steffen_b (mit Fußnote zum Forumsartikel gekennzeichneter Abschnitt zu Eventlircd)

Quote

Die Autorenschaft ist über Asciidoc nicht so transparent zu machen so wie das im Wiki möglich ist, wo jede Änderung einen Autoren hat.

Stimmt, ist ein berechtigter Einwand. Lässt sich aber mit einer Fußnote pro Zeichen, Wort, Satz oder Abschnitt lösen wenn man es drauf anlegt. So wie in jedem gedruckten Werk auch (wie ist das in den aus der Wikipedia erstellten Büchern gelöst?)

Quote from hepi

Was heißt das denn genau in der Praxis?

Solange es etwas Textbasiertes ist, das jemand gerne in die Dokumentation aufgenommen sehen würde, baue ich es ein. d.h. ich verlange von niemandem, dass er sich um die Formatierung in asciidoc-Syntax gedanken machen muss.

Also für meinen Teil braucht es keine Fußnote, keine Ahnung ob nun FDL oder CC License oder was auch immer, alles super ...

Hi,

also ich finde die asciidoc Lösung nicht verkehrt. Gerade das lesen eines Buches ist viel einfacher als Anfänger als ein Wiki (imho). Da man aus dem Text später Wiki machen kann, sehe ich da überhaupt keine Probleme in der Zusammenarbeit. (Wenn es denn wirklich eine gibt?!) Man kann ja die Änderungen ins asciidoc zurück pflegen. Außerdem finde ich es gut auch ohne Internet später die Dokumentation über die Installation zu verteilen zu können. (Release bezogen). Das geht auch nicht so einfach mit dem Wiki. Gerade mit Github, kann man mit 1 klick (Anmeldung vorausgesetzt) ein Projekt forken, den Text online direkt editieren und im Anschluss per Pull-Request an uns senden. Ja, das ist etwas aufwendiger, aber ich ich glaube nicht das normale Nutzer großartig Texte beisteuern. Und hier hat ja seahawk1986 das Angebot gemacht: "gib Text, ich mache Buch" Ich kann dich aber verstehen Hepi. Aber mal ehrlich, es kostet böse gesagt uns nichts ihn das Handbuch schreiben zu lassen. Und ins Wiki übernehmen, lässt sich das ganze ja auch weiter hin, wenn das Projekt doch scheitert. Im schlimmsten Fall, haben wir ein Handbuch für Anfänger

Das einzige was geklärt sein muss und imho das wichtigste ist, ist das alle Texte von allen Autoren immer einer gemeinsamen Lizenz unterliegen.

zu früher Wunsch: Ich überlege gerade das Handbuch über den VDR als Plugin direkt lesbar zu machen. Das geht bestimmt auch schön mit asciidoc, evtl sogar mit Bildern (hust: truecolor)

Quote from traxanos

Das geht bestimmt auch schön mit asciidoc, evtl sogar mit Bildern (hust: truecolor)

Als manpage kann man es AFAIK sowieso exportieren, das Problem sind komplexe Formatierungen. Aber ein Browser ist bei yaVDR ja sowieso an Bord und da fast alles bei der Konfiguration über das WFE laufen soll stößt der Nutzer da schon früher oder später drauf.
In Github bin ich noch nicht so ganz drin, die Wikis für ein Projekt kann man dort ja auch mit asciidoc befüllen, aber auch hier scheinen die Formatierungsmöglichkeiten im vergleich mit einer vollwertigen Lösung begrenz zu sein. Damit eignet es sich sicher gut als Versionierungssystem (das ich noch nicht ganz durchblicke, aber das hochladen von Dokumenten klappt schon mal) aber leider nur begrenzt dafür eine Vorschau der Seiten anzuzeigen und die Online-Bearbeitung zu ermöglichen, wie man im direkten Vergleich relativ schön sehen kann (keine Fußnoten, keine Anker und Links innerhalb des Artikels usw.):
https://github.com/seahawk1986/yaVDR-Doku/wiki/50_Remote
http://dl.dropbox.com/u/960809/yaVDR_doc.html#_fernbedienung

Wenn seahawk nun ein Dokument schreibt, das beim Asciidoc-PDF-Export als 160-Seiten-Dokument rausfällt, dann ist das als Buch oder eBook geschrieben worden und kann dann auf einem Tablet oder am Laptop oder ausgedruckt gelesen werden.

Ohne umgeschrieben worden zu sein zu einer anderen Textsorte, eignet es sich aber meines Erachtens nicht als On-Screen-Online-Doku, weder innerhalb des Truecolor-OSDs noch als manpage. Wer liest denn bei Problemen mit dem VDR am FullHD-TV die Doku mit Fußnoten durch? Das scheint mir wenig realistisch im Jahre 2011. Natürlich kann man es der Distri beipacken, aber genutzt werden würde es eher nur im Notfall, wenn keine Internetverbindung da ist. Es wäre auch ein Nachteil, an zu vielen Orten verschiedene statische Versionen der Doku zu verteilen, von denen dann manche einen älteren Stand haben als andere. Im Endeffekt geht der User immer zur Online-Version, wenn er sicher gehen will, dass er den neuesten Stand der Doku bekommt.

Die anderen Export-Funktionen von Asciidoc (HTML, PDF) haben doch da einen viel höheren Stellenwert für den Leser als Manpage + OSD-Doku. Ich würde mich in der Diskussion jetzt auf die Formate HTML + PDF + eBook beschränken, alles andere ist doch nebensächlich.

Ich schlage vor, Ihr Asciidoc-Fans zeigt mal, wie das dann auf Githib in der Praxis aussieht. Macht mal ein Github-Projekt, packt den Doku-Quelltext da rein und arbeitet an einem Generator, der neue HTML-Versionen kompiliert und publiziert, nachdem jemand einen neuen Commit gemacht hat. Zeigt mir, dass es geht, denn das Wiki kann es schon jetzt.

Gruß
hepi

Quote from hepi

mal sehen was er zauber und was nicht vielleicht sollte man einfach 2gleisig fahren. ein handbuch und ein wiki. welches die gleichen textschnipsel verwendet.

ich finde handbücher generell besser zu lesen als ein wiki auch auf einem bildschirm!