yaVDR-Dokumentation verbessern: Wer macht mit?

Hier mal ein Link zu einem, wie ich finde, ganz guten Artikel zum Thema "Multilinguale Wikis":
Klick!

Spiff

Er muss garkein Coder sein.

Ich hab auch schon einiges im Wiki dokumentiert. Ich glaube ganz gut. Als Coder würde ich mich nicht bezeichnen.

Es geht doch v.a. darum, dass man ein gelöstes Problem/wenn man etwas gelernt hat, dieses auch dokumentiert.

Bei mir war das z.B.:

• Bootet nicht kann bedeuten, dass ein fsck durchgeführt wird. Geduld!
• die Startskripte liegen in /etc/init/ nicht in init.d
• ...

Vielleicht ein anderer Ansatz:
Wäre ein Punktesystem möglich, bei dem man für das Editieren von Wiki-Artikeln Punkte bekommt. Bei jemandem, der viel im Wiki hilft, ist man dann auch hilfsbereiter wenn er mal Hilfe benötigt.

Interessante Entwicklungen hier in diesem Thread! Schön!

Ein paar Anmerkungen:

1) Das reine Aufsetzen einer neuen technischen Plattform für Dokumentation (genannt wurden Wiki und Forum) ist eigentlich das kleinste und unwichtigste Problem, das wir haben. Das geht schnell, löst aber keines unserer Grundprobleme. Ein jungfräuliches Mediawiki setze ich in 20 Minuten auf, aber ich muss auch davon überzeugt sein, dass es der richtige Weg ist, den zahlreichen schon existierenden Wikis (vom Portal und von anderen VDR-Distris) noch ein weiteres Wiki hinzuzufügen. Und das bin ich nicht.

2) Es gibt schon jetzt - abgesehen von unserem momentanen Haupt-Dokumentations-Platz VDR-Portal einiges an Content-Dumping-Infrastruktur, was wir in den letzten 15 Monaten für yaVDR aufgebaut haben:

a) Unsere Website basiert auf dem CMS TYPO3 und ist von mir so konfiguriert, dass man jede Seite parallel in mehreren Sprachversionen anlegen kann (was aus Zeitgründen nicht passiert ist - Englisch ist am wichtigsten). Man könnte also theoretisch auch einfach auf unserer Website dokumentieren, obwohl der Einarbeitungsaufwand für neue Redakteure in TYPO3 im Vergleich mit einem Wiki relativ hoch ist. Es entspricht aber auch gar nicht dem Wiki-Ansatz, weil die Seiten nur von authentifizierten Redakteuren gepflegt werden können und nicht von jedermann. Prinzipiell bin ich (und ich spreche auch nur für mich, habe die anderen nicht gefragt) auch nicht abgeneigt, dass Team-externe VDR-Experten, wenn sie wollen, in unserem yaVDR-Blog über VDR-News bloggen können, wenn sie das wollen und wir ein Thema und seine Aufbereitung gut finden. Aber das läuft neben der Dokumentation.

b) Ich habe vor einem halben Jahr ein auf phpbb3 basierendes Forum eingerichtet, welches wir vor allem für unseren internen yaVDR 0.3 Beta-Test verwendet haben. Das Forum ist da, aber wir wollen es nicht in ein öffentliches Forum umwandeln, weil seine Administration zu viel Arbeitsaufwand für uns ist NEBEN der Weiterentwicklung von yaVDR. Das nur zum Verständnis.

3) Das Wiki-Prinzip mag manche Autoren anziehen, die nur ein paar Details hinzufügen wollen, andere Autoren aber wegen der Anonymität und der kollektiven Urheberschaft abschrecken, weil Anerkennung für's Schreiben dort für den an jeder Formulierung feilenden Einzelautor nicht so leicht zu bekommen ist. Fakt ist, dass das VDR-Wiki hier im Portal darunter leidet, dass nur eine unermüdliche Minderheit dort regelmäßig den Content pflegt, strukturiert und katalogisiert, und für viele Neulinge das Portal und das Wiki zwei getrennte Welten sind, zwischen denen sie nicht gewillt sind, zur Informationsbeschaffung hin und herzuspringen. Dieses Problem wird auch ein neues, frisches, leeres yaVDR-Wiki erben, solange kein Konzept und keine Autoren-Mannschaft bzw. Eigeninitiative da ist.

4) Es gibt in der VDR-Community viele Sub-Teams, die eigentlich ähnliche Wünsche und Ziele haben. Wann immer möglich und thematisch sinnvoll, sollten Inhalte für möglichst viele dieser Teams wiederverwendet werden können, auch um die schon geleistete Vorarbeit anderer zu respektieren und nicht zu "plagiatisieren" (Wort des Jahres 2011) und andere Autoren zu kränken, die ihren Content plötzlich vielleicht in einem anderen Wiki kopiert wiederfinden (Creative Commons Licence nutzen oder etwa was anderes??? Muss alles entschieden werden) .

5) Für mich wäre die Dokumentation von einzelnen VDR-Plugins zum Beispiel ein Thema, welches nicht unbedingt in einem distributionseigenen Wiki erfolgen muss, sondern in einem allgemeinen Wiki gut passieren kann. Andererseits ist das Koordinieren von Dokumentation mit anderen Teams aufwändig und es ist schwer genug, überhaupt Motivierte zu finden, die Zeit haben. Und wenn wir tatsächlich in Englisch dokumentieren würden, müssen auch die externen Links zu englischem Content führen. Sehr vertrackt.

5) Hardware-Fragen wie Treiber-Diskussionen oder Kaufberatung zu konkreten Mainboards und DVB-Karten würde ich wegen der Schnellllebigkeit der Produkte eher in einem Forum behandelt sehen als in einer (wiki-)Dokumentation. So ein Forum müsste dann hinreichend detailierte Unterforen aufweisen, damit Hardware-Diskussionen geordnet werden können. Je ordentlicher ein Forum strukturiert ist, desto eher kann es als Nachschlagewerk genutzt werden.

6) Ein Konzept muss her für die Doku: Warum wollen wir denn eigentlich mehr dokumentieren? Nur, damit die Fragenflut bzgl. yaVDR im VDR-Portal eingedämmt wird? Dann müssen wir uns an der Häufigkeit der wiederkehrenden Fragen orientieren und die Zielgruppe wären blutige Einsteiger - was die Menge an anzubietendem Grundlagenwissen erhöht, das könnte aber auch erstmal auf eine Erweiterung der FAQ herauslaufen. Wer ist die Zielgruppe? Wie soll gegliedert werden? Braucht es eine Guideline für Autoren, was in die Doku soll und was nicht und wie die Texte aufgebaut sein sollen?

7) Gliederung: DerG hatte hier mal eine Gliederung angefangen unter: http://www.vdr-wiki.de/wiki/in…DR-Installationshandbuch. Das kann man ja mal anschauen, um zu entscheiden, ob man es so oder ganz anders machen will.

Angenommen, es melden sich hier noch weitere erfahrende VDR-Veteranen, die gewillt wären Doku zu schreiben: Vielleicht ist es besser, einfach jeden zu fragen, auf welches Einstiegstehma er Lust hat. Jeder soll erstmal als Motivationsbeweis 500 Wörter (oder eine andere Zahl) zu einem selbst gewählten Thema abliefern. Die Themen und Autoren kann man ja irgendwo auflisten, damit es keine Themen-Doppelungen gibt. Danach schaut man sich die Texte an, die herausgekommen sind, und erarbeitet darauf aufbauend ein paar Guidelines und eine Gliederung. Dann schaut man: Welche von diesen Texten kann man schon veröffentlichen? Welche Verbindungsstücke fehlen, um die nächsten zu veröffentlichen?

9) Ohne Unterstützung durch das Dev-Team wird es für die Autoren nicht gehen.

10) Immer im Hinterkopf behalten: Die unheimliche Schnell-Lebigkeit. Jeder Content, den man schreibt, ist schon nach 3-6 Monaten veraltet. Wenn man Glück hat, muss er nur ergänzt werden, manchmal aber komplett umgeschrieben werden.

...

Mehr fällt mir gerade nicht ein.

Gruß
hepi

Ich würde das alles irgendwie zusammenfassen.

Auf die Startseite des Wikis UNBEDINGT eine Newsbar. (Wie letztesmal als kurze zeit kein Update gefahren werden sollte) sowas gehört da hin. UND mMn ganz wichtig: Ein Changelog. Bei jedem verfügbaren apt-get update sowie apt-get dist-upgrade sollte auch dementsprechend ein Changelog erstellt werden.

Dann zum eigentlichen Wiki. Weiß nicht ob jemand meine Idee überlesen hat, aber vom Aufbau her würde ich dass schon fast am idealsten finden:

Drop Down- Menüs, welche je nach auswahl genau die Probleme+Lösungen anzeigen die ich mit meiner Hardware habe / haben könnte.

Und dann noch (Finde den Aufbau bei Ubuntu wirklich mehr als stark) einen Walkthrough vom Download bishin zum Einrigen des letzten Plugins.

Idealerweise sollten wir das vielleicht mit allen Interessierten mal in nem IRC abklären?
Würde die Ergebnisse dann zusammentragen und einen Thread erstellen. Dann könnte abgestimmt werden was gewünscht wird und was nicht.
Und dann natürlich auch eine Kontaktadresse/Kontaktlink auf der yaVDR Homepage mit einem vorgefertigten Formular like:
Wikieintrag einsenden:

Problem mit:
(falls Hardwarespezifisch:) Hardware:
Lösungsdetails:
usw...

Wenn eine Hand voll Leute sich bereit erklären würde das zu machen, müsste noch nichtmal jeder User in dem Wiki rumschreiben. Somit hätten wir immer den gleichen Aufbau. Da es ja auch immer die selben Personen machen!
Und das ganze eben Vom Verzeichnis ändern, über Reps hinzufügen usw. Wirklich für jeden User! Und sei es noch so ein Blutiger Anfänger!

Dann natürlich noch das Ganze hier im Forum anpinnen und drauf Verlinken

Hi.

I do not know for sure what is here written, because the translator from german to Spanish do not make very well his work but it seems that some people have the will to improve the documentation of yavdr for "not advanced" users, by mean a wiki.

If it is true, I can help for the Spanish translation. As I am sure that many other Spanish speakers (not only from Spain) uses yavdr, I would like to know their opinion, in this thread or opening a new one (in english, if possible). The request is extensive to other launguage speakers.

Regards.
jbjbjb

You´re right jbjbjb

we´re exactly talking ´bout how to improve the documentation of yavdr and make it possible to understand ans solve their problems for beginners.

We´re also talkin about translating it to other languages. Mainly english of course.

The reason why you can´t read or translate our sentences properly is that we´re not talkin in straight german The dialect....

Zitat

Original von WastlJ
UND mMn ganz wichtig: Ein Changelog. Bei jedem verfügbaren apt-get update sowie apt-get dist-upgrade sollte auch dementsprechend ein Changelog erstellt werden.

In jedem geänderten Paket ist ein Changelog und da gehört es auch hin.

Gerald

Zitat

Originally posted by WastlJ
The reason why you can´t read or translate our sentences properly is that we´re not talkin in straight german The dialect....

Thanks for the warning. Well.... Google needs improvements too.

Meine persönliche Meinung:

Erfahrunsberichte, FAQ, Troubleshooting im vdr-wiki erwarte ich ein Stück weit das das durch alle User getragen wird. Die Einstiegshürden sind niedrig, die Arbeit nicht riesig, und es ist in jedem Fall hilfreich. -> vdr-wiki !

Dokumentation wie von Wicky und Hepi gedacht: Auja ! Bitte !

jbjbjb: You are welcome to translate it to spanish , once we have a starting in english

Hallo,

Zitat

Original von Spiff
Hier mal ein Link zu einem, wie ich finde, ganz guten Artikel zum Thema "Multilinguale Wikis":
Klick!

Danke Spiff, werde ich mir mal durchlesen!

Zitat

Original von WastlJ
Auf die Startseite des Wikis UNBEDINGT eine Newsbar. (Wie letztesmal als kurze zeit kein Update gefahren werden sollte) sowas gehört da hin. UND mMn ganz wichtig: Ein Changelog. Bei jedem verfügbaren apt-get update sowie apt-get dist-upgrade sollte auch dementsprechend ein Changelog erstellt werden.

Ein Changelog hört sich für mich eher nach einem RSS-Feed (oder Blog-Unterkategorie) an, nicht so sehr nach Wiki-Content. Ein gutes Wiki hat aber auch Bots, welche automatisiert Content in ein Wiki einfügen, so könnte dann der Inhalt eines RSS-Feeds auch automatisch in einem Wikl landen, wenn man es denn da haben will. Für mich ist aber die Entscheidung, ob ein Wiki das Gelbe vom Ei ist, noch nicht gefallen.

Zitat

Original von WastlJ
Dann zum eigentlichen Wiki. Weiß nicht ob jemand meine Idee überlesen hat, aber vom Aufbau her würde ich dass schon fast am idealsten finden:

Drop Down- Menüs, welche je nach auswahl genau die Probleme+Lösungen anzeigen die ich mit meiner Hardware habe / haben könnte.

Und dann noch (Finde den Aufbau bei Ubuntu wirklich mehr als stark) einen Walkthrough vom Download bishin zum Einrigen des letzten Plugins.

WastlJ, kannst Du die Beispiele von Ubuntu-Forum.de, auf die Du verweist, mal konkret verlinken? Ich finde das nicht in dem Wiki mit den Dropdown-Boxen. Ich bin gekommen bis: http://wiki.ubuntu-forum.de/index.php/Portal

Gruß
hepi

Zitat

Original von hepi

Die verlinkten Wikiseiten sagen mir persönlich auch sehr zu.

Inyoka ist laut dieser Seite [1] weder als closed noch als open source Version verfügbar.

Was nicht heißt, dass man nicht trotzdem Textboxen mit anderer farblicher Formatierung in einen Wikitext gesetzt bekäme, die die Gültigkeitsdaten enthalten können. Dafür könnte man in Mediawiki Templates anlegen.

Ich würde sogar für einen Bot plädieren, der jede Wiki-Seite, die seit 6 Monaten nicht mehr geändert worden ist, mit einer Warnung am Seitenanfang versieht, dass der Inhalt wahrscheinlich nicht mehr aktuell ist. Das wäre übrigens auch was für's VDR-Wiki.

Ich diskutiere die Dinge gern lang und breit, ohne eine schnelle Entscheidung zu forcieren. Wenn hier jemand zu ungeduldig ist, und mit dokumentieren gleich durchstarten will, soll er einfach anfangen und was schreiben, beispielsweise die yaVDR-FAQs erweitern im VDR-Wiki um oft gestellte Anfängerfragen. Das würde ich sehr schätzen.

Falls Ihr den Eindruck habt, ein langer Doku-Thread hier im Portal ist zu wenig Raum, um dieses Doku-Thema übersichtlich zu diskutieren, können wir gern für Euch entweder eine yaVDR-Doku-Mailingliste anlegen oder einen eigenen Foren-Bereich in unserem Team-Forum. Das Forum hätte den Vorteil, dass man sein Geschriebenes hübscher formatiert ablegen kann als in einer ML.

Gruß
hepi

[1] http://behind.ubuntuusers.de/2…ka-noch-nicht-open-source

Zitat

Original von hepi

WastlJ, kannst Du die Beispiele von Ubuntu-Forum.de, auf die Du verweist, mal konkret verlinken? Ich finde das nicht in dem Wiki mit den Dropdown-Boxen. Ich bin gekommen bis: http://wiki.ubuntu-forum.de/index.php/Portal

Gruß
hepi

Diese Dropdownboxen sind eine Idee von mir. Der Aufbau von den Ubuntu Seiten wurde hier schon mal gelobt. Links weiter oben

Die Idee mit dem Bot zwecks aktualität ist super!

Zitat

Original von WastlJ

Diese Dropdownboxen sind eine Idee von mir. Der Aufbau von den Ubuntu Seiten wurde hier schon mal gelobt. Links weiter oben

Ach so, ich habe das mit Tuxi70s Posting verwechselt. Tuxi70 verweist auf http://www.ubuntu-forum.de/, das ist übrigens ein komplett anderes Forum als http://ubuntuusers.de/:

Zitat

Original von Tuxi70
Wie wäre es, wenn man es so handhabt wie auf http://www.ubuntu-forum.de/ ? Denn die haben ein WIKI eingerichtet, wo jeder seine Erfahrungen mit seinem System verfassen kann. Dieses kann man dann unterteilen nach Hardware, ob diese dann auch mit Linux läuft und wie diese denn auch konfiguriert wird.

Tuxi70: Ich finde das im Wiki dort nicht, wo die Leute ihre Erfahrungen aufschreiben.

@WastlJ: Dropdownboxen hören sich für mich nach einer maßgeschneiderten Hardware-Datenbank-Anwendung an, das klingt recht aufwändig. In einem Wiki würde man wohl dann normalerweise mit Kategorien arbeiten, um ein Pendant zu solchen Menüs zu bekommen: http://www.mediawiki.org/wiki/Help:Categories

Zitat

Original von WastlJ
Die Idee mit dem Bot zwecks aktualität ist super!

Das ist hier beschrieben:
http://www.mediawiki.org/wiki/Manual:Bots
http://en.wikipedia.org/wiki/Wikipedia:CREATEBOT
http://en.wikipedia.org/wiki/Wikipedia:Bots/Status

Gruß
hepi

Zitat

Original von WastlJ
Diese Dropdownboxen sind eine Idee von mir.

Wiki-Abfragen ähnlich einer Datenbankabfrage, die bestimmte Suchkriterien enthält, wären möglich mit einem Semantic Media Wiki. Dabei werden alle Seiten mit typisierten Semantik-Properties angereichert:

http://de.wikipedia.org/wiki/Semantic_MediaWiki
http://semantic-mediawiki.org/wiki/Semantic_MediaWiki

Beispiel:
http://de.wiki-products.org/Apple_iPhone
http://de.wiki-products.org/index.php?title=Apple_iPhone&action=formedit

Gruß
hepi

Also, ich bin ja gerade schwer begeistert von Semantic MediaWiki. Habe mich da gerade eingelesen. Damit wird es beispielsweise möglich, für bestimmte Kategorien in der Dokumentation mit vorgefertigten Eingabemasken zu arbeiten, was beispielsweise für DVB-Geräte, für Mainboards, für Nettops oder auch für VDR-Plugins die Dateneingabe formalisieren würde, was hoffentlich eine Erleichterung für konsistente Daten wäre. Beispiel für eine Eingabemaske, um eine neue Wiki-Seite einer bestimmten "Kategorie" anzulegen:

http://www.placeography.org/index.php?title=470_Hopkins_Street%2C_Saint_Paul%2C_Minnesota&action=formedit

Wenn man eine Mainboardliste so abgelegt hat, kann man dann hinterher eine Query machen: Mache mir mal automatisch eine schöne Tabelle mit allen Mainboards, die einen Onboard-ION-Chipsatz und auch PCIe-Steckplätze haben.

Ein Semantik MediaWiki erlaubt dann auch, weil die Daten typisiert sind, die Inhalte zu exportieren und zu importieren. Beispiel: linuxtv.org kommt auf die Idee, die DVB-Devices in ihrem Wiki nach den Regeln von Semantic MediaWiki abzulegen, also mit typisierten Eigenschaften. Dann könnten andere Wikis wie das VDR-Wiki, oder die Wikis anderer VDR-Distributionen, oder das Wiki von MythTV oder TVHeadend über Import-Funktionen diese Seiten automatisch regelmäßig importieren. Damit muss ein User zum Lesen nicht mehr von einem Wiki zum anderen springen, bearbeitet werden die Daten aber nur beim ursprünglichen Upstream-Wiki (wo man manuell hinsurfen muss). Das würde heißen, dass sowohl User von MythTV, TVHeadend und VDR zu linuxTV.org pilgern, wenn sie Daten ergänzen oder aktualisieren wollen. Damit wäre hoffentlich eine aktuellere Datenbasis zu erreichen.

Gruß
hepi

So, ich setze mal meinen Monolog fort:

Ich habe ja schon mehrmals angedeutet, dass ich gern vor allem die englischsprachige VDR-Dokumentation ausbauen würde. Grund ist, dass ich wünsche, dass der VDR international noch bekannter wird und die internationale VDR-Community wachsen kann, um auch über das nächste Jahrzehnt noch viele neue und spannende VDR-Plugins und Addons zu Gesicht zu bekommen (und nicht einfach so TVHeadend und MythTV das Rennen um das favorisierte XBMC-TV-Backend gewinnen lassen).

Was mir jetzt aber klar geworden ist, dass eine nicht-existierende internationale Community auch keine englischsprachige Doku pflegen kann. Das heißt, für den Aufbau einer internationalen englischsprachigen Community braucht man zunächst ein englischsprachiges VDR-Forum, weil am Anfang steht die FRAGE. Neue User wollen Fragen stellen, und wenn die Fragen beantwortet werden, entsteht dadurch die erste Form von englischsprachiger Doku. Wenn es dann zu unübersichtlich wird, wird dann die englischsprachige Community irgendwann damit beginnen, nach einem Wiki zu rufen, welches sie dann nach ihrem Gusto mit Content füllen werden.

Zusammengefasst: Erst eine englischsprachige Community über ein rein englischsprachiges Forum aufbauen, erst später wird ein englischsprachiges Wiki wichtig. Damit so etwas funktionieren kann, brauchen wir aber viele VDR-Portal-User, die bereit sind, auf Englisch dort mitzuposten. Die Einstiegshürde ist dabei aber geringer, als wenn man ganze Wiki-Seiten auf englisch schreiben soll.

Die englischsprachige VDR-ML halte ich für ungeeignet für VDR-Einsteiger als Foren-Ersatz. Das ist ein Developer-ML mit einem kleinen aber feinen Expertenkreis. Das VDR-Portal halte ich auch für ungeeignet zur Gründung einer internationalen Community, da das Nebeneinander von Deutsch und Englisch und die inhaltliche Vielfalt von 10 Jahren VDR-Entwicklung Einsteigern nicht entgegen kommt.

Gibt es Leute hier, die zwar keine Lust auf deutsche Wiki-Doku schreiben haben, aber Lust darauf haben, ein englischsprachiges VDR-Forum zu gründen?

Gruß
hepi

Hepi, du driftest komplett ab ...

Es geht hier um yavdr Doku, die englisch, gut verständlich und evtl auch übersetzt werden soll. Nicht mehr und nicht weniger. Alles andere interessiert in diesem Zusammenhang garnicht.

Aus rein praktischen Beweggründen, sollte zuerst geklärt werden, wie das ungefähr aussehen soll, Ziele , Form, wenn das geklärt ist, welches Tool man verwendet. Wenn das geklärt ist, müssen wir zusehen das wir schnellstmöglich die technische Basis liefern können, damit dann jeder der Lust hat und fähig ist, loslegen kann.

Ich würde mir wünschen das, was auch immer dann entsteht, dieses gleich auf unstable/testing basiert, damit evtl. eine erste Version auch als Offline Version mit dem nächsten Release ausgeliefert werden kann.

Nabend!
Melde mich ja nur ungern in diesem Thread, zu schnell hat man einen Job am Hals

Unter http://www.vdr-wiki.de/wiki/index.php/YaVDR ist doch schon einiges vorhanden, wenn auch noch weiter Sortierungsbedürftig. Just for fun mag ich zumindest mich nicht durch ordentlichen englischen Satz quälen und ich denke das mag auch Anderen so gehen.

hepi
Hoher Anspruch und Du hast sicher recht, aber user die wirklich gutes Englisch können sind doch ehr weniger als deutschsprachige, schau dir nur das englische VDR-Wiki an.

Eine Echte Dokumentation ersetzt das natürlich nur zum Teil, aber wer mag schon eine monatlich zu aktualisierendes Manual von hunderten Abschnitten pflegen.

Und ja auch eine englische Doku ist nötig wird aber soweit ich mich entsinne eh immer als README mit jedem deb ausgeliefert, schaut nur keiner hinein (schließe mich da ein).

Gruß und schönen Fernsehabend
Ulf