DokumentationImWiki

Dieser Artikel soll den Nutzen von ZWiki, speziell dieses Wikis auf dzug.org f�r die community erl�utern.

Von FlorianKonnertz

Pers�nliche Vorbemerkung

Ich engagiere mich f�r dieses Wiki, da ich meine da� damit die Dokumentation f�r Zope elegant und effektiv weiter ausgebaut werden kann und dies auch Spa� macht. Ich habe in den letzten Monaten mich stark an der Dokumentation von ZWiki auf dem hauseigenen ZWiki auf http://zwiki.org beteiligt, in meinem eigenen NooWiki dokumentiere ich so ziemlich alles was ich auf Zope und Linux mache und es erf�llt seinen Zweck sehr gut. Ich denke mir, da� es f�r die community die sich auf dieser Site und in den Listen tummelt auch eine gute Sache ist und ich m�chte in diesem Artikel die Arbeit im Wiki erl�utern und erz�hlen, wie ich mir das so vorstelle.

Kommunikation im Wiki

Diskussion �bers Web.

Wikis k�nnen von jedermann anonym editiert werden. Dies geschieht im StructuredText?-Format (stx), es kann bei ZWiki aber auch HTML (u.a.) zus�tzlich verwendet werden. Damit ist die Eingabe neuer Texte bzw. die Mitarbeit an bestehenden Texten einfach und effektiv m�glich. Jeder kann Korrekturen und Erweiterungen in den Seiten sofort vornehmen, beispielsweise f�gt man einfach in den fortlaufenden Text eine Bemerkung in kursiver Schrift ein, evtl. mit Signatur. Das ist cool! - FloK,03-28 - Bei l�ngeren Beitr�gen wie zB Fragen zum Dokument benutzt man die Form am Ende der Seite: Sie f�gt einen signierten Kommentart mit �berschrift der Seite hinzu. Andere k�nnen darauf in gleicher Weise antworten, so ist eine Diskussion m�glich. Der Nachteil ist hier, da� im Gegensatz zur Mailingliste der Thread nicht so einfach verfolgt werden kann. (Hier gibt aber schon die M�glichkeit, ZWiki mit den Mailinglisten zu kombinieren, mehr dazu im n�chten Abschnitt.) Die Diskussion in ungeordneter Weise ist bei vielen Themen aber auch v�llig ausreichend. Sie wird meist nach einigen Tagen beendet sein und verbleibt erstmal auf der Seite. Das/Die Ergebnisse werden nach einiger Zeit (zwei Wochen haben sich als angemessen herausgestellt) von einem der Beteiligten zusammengefasst im Artikel der Seite untergebracht, die Diskussion auf einer eigenen Seite archiviert und evtl. offen gebliebene Fragen noch einmal in einem Abschnitt der Seite zusammengefasst. Ist ein Thema dauernd im Gespr�ch, so bietet sich an eine eigene Seite "ThemaXyzDiskussion?" einzurichten, die regelm��ig archiviert wird. (Als Beispiel m�gen ZWiki:SubWiki, ZWiki:SubWikiDiscussion, ZWiki:SubWikiDiscussionArchive dienen.)

Wiki und Mail

ZWiki bietet die M�glichkeit sich f�r beliebige Seiten bzw. f�rs ganze Wiki zu subcriben und alle �nderungen per Email geschickt zu bekommen. Auf die Mails kann auch per Mail geantwortet werden, so kann am Wiki wie an einer Mailingliste auch rein �ber den Mail-Client teilgenommen werden. In allen Mails ist ein Link auf die jeweilige Seite enthalten, so kann man sich das Ganze bei Bedarf auch in der �bersicht ansehen. Die Mails haben den Titel der Seite im Betreffs-Feld sowie ein K�rzel f�r den Mail-Filter. ZWiki kann mit den Mailinglisten-Tools MailMan? und MailBoxer? verbunden werden um diese Medien zu bereichern. So kann man, wenn die Diskussion eine gewisse L�nge �bersteigt, den Thread sich im Archiv der Mailingliste anzeigen lassen. Zusammen sind sie ein unschlagbares Team.

Wiki = Mail + Web ?

Es ist ein m�gliche Form der Verbindung der Medien Web und Email, dies bringt leider Abstriche in beiden Bereichen mit sich. Wie oben erw�hnt, kann man die Threads nicht so gut verfolgen. Das Web an sich hat nat�rlich den Vorteil der besseren Gesatltungsm�glichkeit mit Grafiken und sch�nerem Design. Im Wiki finden sich idealerweise Texte, die arm an Grafiken, aber reich an Interaktivit�t und gleichzeitig st�rker vernetzt sind als es im WWW der Fall ist.

Verlinken im Wiki

NamesKonventionen

Die grundlegende Eigenschaft von Wiki ist die M�glichkeit der einfachen Verlinkung von Seiten. Das Konzept der WikiLinks? besteht darin, da� der Link genauso aussieht wie der Titel der verlinkten Seite, es sind also keine URLs? notwendig. Unterst�tzt werden in erster Linie Links, die ein, zwei oder wenige W�rter lang sind. Im laufenden Text kann man so ohne M�he links setzen indem man das bzw.die gefragten W�rter als "WikiNamen?" schreibt, d.h. zusammen mit beibehaltenen gro�en Anfangsbuchstaben. Bei Links. die nur aus einem Wort bestehen mu� man sich auf geeignete NamensKonventionen einigen. Hier kann es vorkommen, da� ein Wort in allen Schreibweisen komisch aussieht, damit man es doch im Text erw�hnen kann, kann man auch eine Platzhalter-Seite erzeugen, die auf die eigentliche Seite verlinkt.

Links im fortlaufenden Text

Bei der Erstellung neuer Seiten sollte man darauf achten, da� der Titel der Seite m�glichst im fortlaufenden Text genannt werden kann (oder selbst einen Satz bildet, wie bei dieser Seite). Es sind also weder HTML-Tags (a href=""...) noch STXLinks? link notwendig, sie k�nnen aber dennoch verwendet werden. Links im HTTP-Stil (https://dzug.org) und werden erkannt, sie kopiert man einfach aus dem Browser r�ber. Bookmarks und Resourcen k�nnen so schnell gesammelt und kommentiert werden.

RemoteWikiLinks

Dies sind Links zu Wiks auf anderen Servern. Damit hier auch erspart bleibt, die URL jedesmal einzugeben, wird eine Seite mit dem Schl�sselwort RemoteWikiURL: gefolgt von der URL erstellt. Dann kann auf allen Seiten des Wikis auf beliebige Seiten des remote Wikis verlinkt werden, indem man das K�rzel und den Namen der gew�nschten Seite mit einem Doppelpunkt verbindet. Beispiel: NooWiki:ZOpe ; auf NooWiki steht das Schl�sselwort. Es ist ebenfalls m�glich, URLs? von beliebigen Diensten wie zB GooGle anzugeben, um eine Bezeichnung einfach an die andere Seite zu �bergeben. Beispiel: - siehe auch RemoteWikiLinks?

FreieLinks

W�rter, die ihre Schreibweise behalten m�ssen, weil es Spezialbegriffe sind, werden mit eckigen Klammern zu Links gemacht. Bsp: [ ]? - So k�nnen auch wichtige Module, Funktionen und Objekte auf Unterseiten erkl�rt werden, soll sp�ter von einem anderen Text referenziert werden, so kann ohne die URL rauszusuchen einfach verlinkt werden. - (siehe FreieLinks?)

Probleme

Es besteht hier die Gefahr, da� sich so viele Links in einen Text einschleichen, so da� er un�bersichtlich wird. Der ge�bte Hypertext-Konsument wird zwar gelernt haben, welche Links er mal eben so aufruft und welche nicht, dennoch wird man auch im Wiki hin und wieder einen Link vermeiden wollen, dies ist durch voranstellen eines ! m�glich, zB.: ZWiki - auch die �berschriften in diesem Kapitel w�rden fast alle auf weitere Seiten verweisen, was aber bei �berschriften am wenigsten gewollt ist, da die Erkl�rung ja darunter folgt.

BackLinks

Backlinks sind Links die auf die Seite zur�ckverweisen. Dies ist eine Speziali�t von Wikis und findet sich im normalen WWW nicht, f�r gew�hnlich sind alle Links dort unidirektional. Mit Hilfe der BackLinks? lassen sich die Dinge im wiki besser kategorisieren und damit auffinden. Alle Seiten, die die aktuelle Seite zitieren k�nnen einfach gefunden werden. (Siehe auch WikiKategorien und Wiki Marker.)

Eine �bersicht aller M�glichkeiten mit Links im ZWiki gibts auf ZWiki:WikiLinkingIssues

Zope Dokumentation im Wiki

FAQ

FAQ (Frequently Asked Questions) k�nnen im Wiki gehalten werden, hierzu gibt es eine Seite mit Eingabe-Formular f�r die seltenen Besucher, die nicht das Format der FAQ-Seiten studieren wollen. Hier wird pro Kapitel eine Wiki-Seite gehalten, auf einer Seite befinden sich also mehrere Fragen im Gegensatz zur zweiten Variante, bei der f�r jede Frage eine eigene Seite reserviert ist. Bei kleinen Kapiteln und konkreteren Fragen ist sicherlich die erste Variante vorzuziehen. Die zweite L�sung bietet sich bei allgemeinen Fragen an, da dann zum Thema noch eine Diskussion auf der Seite stattfinden kann. Hier im Wiki ist nun eine Testseite, die die Eingabe in drei Kapitel erm�glicht: FAQs

Allgemeines �ber Dokumentation

Dokumentation umfa�t viele Einzelbereiche. Angefangen von vollst�ndigen Dokumenten, wie zB. dem ZopeBuch, Tutorials und Referenzen bis zu Archiven von Mailinglisten, in denen mit einer guten Suchfunktion die Antworten (hoffentlich) schnell gefunden werden k�nnen, bis zu FAQs und Wikis und den Archiven der Chat-Channels mu� alles vorhanden sein. F�r die meisten Themen gibt es Einf�hrungs-Texte, weiterf�hrende Doku ist schon schwerer zu finden, da die fortgeschrittenen Themen erst dann dokumentiert werden, wenn danach gefragt wird, vermutlich deshalb, weil die meisten fortgeschrittenen Entwickler lieber programmieren als dokumentieren. Dies ist ein nat�rlicher Vorgang: Warum sollte man alles gleich dokumentieren, wenn doch die Leute, die mit diesen Themen umgehen, es ja schlie�lich gut k�nnen. Dokumentation durchl�uft demnach gewisse Entwicklungsstadien. Die verschiedenen Bereiche bzw. Phasen sollten gut miteinander verbunden sein und interagieren, damit jedes Thema seinen passenden Platz findet und es in Umfang und/oder Tiefe leicht ver�ndert werden kann.

Vom Problem zur Dokumentation

Abgesehen von den Grundlagen-Texten und den APIs? sind die anderen Dokumentationen willk�rlich. Es ist das enthalten, nachdem die meisten Leute gefragt haben und was den Schreibern selbst die meisten Probleme gemacht hat (aber nat�rlich auch, was sie am meisten interessiert hat). Die Dokumentation beginnt bei der ersten Frage. Es kommen Antworten dazu, falsche und richtige Ans�tze, manchmal sind die L�sungen eindeutig, meist aber gibt es viele, vollst�ndig ist selten etwas. Die Dokumentation w�chst mit der Zeit immer weiter, sie lebt sozusagen. Die �lteren Texte, die sich als tauglich erwiesen haben werden in die Stamm-Doku aufgenommen und h�ufig referenziert. Texte, die nicht so gut angekommen sind, werden seltener genannt, bis sie irgendwann nicht mehr gebraucht werden, weil die stimmigen Inhalte alle woanders in besserer Verst�ndlichkeit genannt werden. Es ist ein Proze�? der �berarbeitung und Zusammenfassung. Die Teile m�ssen bewertet werden, die Gemeinde der Nutzer bestimmt, was gut ist.

Wiki als Instrument der gemeinsamen Dokumentation

Wiki erm�glicht die einfache Bearbeitung aller Seiten und das schnelle Referenzieren auf Begriffe und Hilfstexte. An Wikis k�nnen alle mitarbeiten, vom Newbie bis zum Profi. Wer Lust hat, etwas zu �ndern und zu verbessern, der kann es ohne Aufschub tun, zumindestens kann er seine Vorschl�ge direkt am Platz einbringen. Die �nderungen werden sofort f�r alle sichtbar und k�nnen best�tigt oder wieder verworfen werden. Die Unterscheidung zwischen Entwickler, Anwender und Dokumenteur ist in diesem Rahmen nicht mehr so bedeutend. Jeder kann nach seiner Begabung arbeiten: Diskutieren, Fragen oder Antworten; Codeschnippsel beisteuern, Begriffe erkl�ren, lange Texte verfassen, Seiten gliedern, ordnen, das Wiki strukturieren, �bersichten erstellen, Resourcen sammeln oder Fehlermeldungen posten. Manche tun sich leicht, die Beitr�ge der anderen zu erfassen und zu �berarbeiten. Dies ist speziell in Wikis eine wichtige T�tigkeit. Die Frage, ob sich daf�r genug Freiwillige finden ist berechtigt, in den meisten Wikis klappt es ziemlich gut. Der Inhalt des Wikis ist das Ergebnis gemeinsamer Arbeit und weil viele Augen mehr sehen, kann Dokumentation im Wiki erstklassig sein. (Siehe dazu: http://c2.com/cgi/wiki?WhyWikiWorks)

Schlu�bemerkung

Ich schreibe gerne Doku, zB. solche Texte hier und �berarbeite gerne die Notizen und Entw�rfe der besch�ftigten Entwickler. Ich gebe sehr gerne meine Erfahrungen weiter und vermittle gerne Wissen. Auch m�chte ich besser in Zope werden, dies ist aber sowieso der Nebeneffekt des Ganzen. Bis dato habe ich eine ansehnliche Menge Resourcen gesichtet und in meinem NooWiki abgelegt. Desweiteren habe ich in anderen Wikis teilgenommen und in den Listen Fragen beantwortet, so gut ich konnte. Es ist mein gro�er Wunsch, an einem lebendigen Wiki in der DZUG teilzunehmen und dazu beizutragen. Ich m�chte in Sachen Zope nur noch ein Wiki nutzen - das der DZUG. Vielleicht hat ja der ein oder andere nun Geschmack daran gefunden ins DZUGWiki einzusteigen, es w�rde mich sehr freuen. - FloK, 04-18