DZUG

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

Von FlorianKonnertz

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.

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.

!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).

http://dzug.org

!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: GooGle?:Zope - 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.

Eine Übersicht aller Möglichkeiten mit Links im !ZWiki gibts auf ZWiki:WikiLinkingIssues

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)

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

• hi florian, ist dieser artikel noch aktuell? lg karl 220806