Wer hat an der Uhr gedreht? Wie die Zeit vergeht, wenn man Artikel schreiben soll - und es wird jedes Mal wieder knapp zum Stichtag hin. Wahrscheinlich geht es den Leuten, die ihre Erweiterungen dokumentieren müssen genauso. Meistens sehen wir Benutzer uns ja nur die Demo an, lesen die Kurzbeschreibung und laden dann das Teil herunter und installieren es ... Aber da fehlt ein Schritt dazwischen; sehen wir uns doch kurz an, warum wir die Doku lesen sollten ...

Im letzten Teil behandelten wir den Aspekt Support , heute sehen wir uns die Dokumentation an, die durchaus einen Teil des Supports des Entwicklers darstellen kann. Hast du eine Erweiterung von einem guten Entwickler gefunden, hast du auch eine brauchbare Doku gefunden! Das heisst jetzt nicht, dass Erweiterungen ohne Doku schlecht sein müssen, aber Dokumentationen sind meistens sehr hilfreich.

Wie helfen sie uns? Ganz einfach: Installation, Konfiguration, Fehlersuche, Zusatzfelder, Verhalten usw. ... alles das ist in einer brauchbaren Doku beschrieben.

RTFM...

Manchmal 'vergisst' man den 100-seitigen Schinken zu lesen, den da irgendjemand verfasst hat; vielleicht wollen wir gar nicht so viel lesen, wir sollten aber ...

Der Entwickler, der eine Doku schreibt, tut das in erster Linie um zu zeigen, wie seine Erweiterung benutzt werden soll, was die Einsatzmöglichkeiten sind und wie man sie konfiguriert. Leider ist es manchmal so, dass die Doku der aktuellen Version des Codes hinterherhinkt, aktuell ist z.B. die Erweiterung schon auf Version 3.0, die Doku blieb aber bei 2.x stehen. Das ist zwar verständlich. Manchmal ist man als Entwickler gezwungen, einen Bugfix oder ein neues Feature einzubauen - und findet nicht die Zeit für das Nachführen der Doku. Meist sind sich die Versionen ja ziemlich ähnlich ...

Eine gute Dokumentation sollte wenigstens aus diesen vier Teilen bestehen: Installation, Konfiguration, Anpassungen (Customizing) und Fehlersuche.

Bei der Installation ist ziemlich klar, was hier beschrieben werden sollte. An die Adresse derjenigen Leute, die sich sicher sind, dass die Installation mit dem Hochladen und Installieren des Pakets abgeschlossen ist: Falsch! Manchmal müssen Plugins hinzugefügt, aktiviert oder andere Plugins deaktiviert werden. Oder es muss an der Serverkonfiguration etwas geändert werden, oder die PHP Einstellungen müssen angepasst werden ... Bei einfachen Erweiterungen ist das natürlich nicht der Fall, aber wenn man wirklichen J!-Saft installiert auf seiner Seite kann dies durchaus notwendig werden. Ich hatte solche Probleme schon, und verwende seither keine Erweiterungen mehr ohne vernünftige Dokumentation.

Und wie steht es mit dem Kapitel Konfiguration? Das kommt darauf an, welche Features die Erweiterung bietet. Ein simpler Newsticker wird entschieden weniger Doku zur Konfiguration brauchen, als eine Erweiterung für Subskriptionen mit einer Menge von Zusatzfunktionen wie Newsletters Zahlungsportale, Auto-Renewal, Benutzergruppen usw ... Ein gutes Handbuch deckt jeden Schritt der Konfiguration detailliert und in die Tiefe gehend ab. Vielleicht sind das dann halt 20 Seiten zum Lesen, das ist aber immer noch besser, als sich die Haare raufen müssen ... Auch wenn nicht alle Funktionen benötigt werden, man sollte es lesen; es könnte ja sein, dass man dabei Funktionen entdeckt, die man später durchaus braucht, oder von denen man nichts gewusst hat ...

Das Kapitel über die Anpassungen ist abhängig von der Erweiterung selbst. Manche Erweiterungen bieten überhaupt keine Möglichkeiten für ein Customizing (ausser via Template Overrides). Bietet sich aber die Möglichkeit von Haus aus an, sollte dieses Kapitel so geschrieben sein, dass man hier Hilfe findet. Ich habe schon eine Seite gebaut mit einer Erweiterung für Subskriptionen, und das entsprechende Handbuch hat mir alle Fragen zur Anpassung beantworten können - ich musste den Entwickler niemals 'stören'.

Schliesslich - zu guter Letzt - Fehlersuche. Die gute Dokumentation deckt auch hier möglichst viel ab. Es ist sicher nicht möglich, hier alles abzudecken, sonst bräuchte man überhaupt keinen Support mehr, nicht? Probleme, die immer wieder vorkommen und immer dieselbe Lösung haben sollten hier abgedeckt sein. Machen wir als Benutzer einen Fehler, der selten vorkommt, müssen wir halt immer noch ein Supportticket eröffnen ...

Zusammenfassend kann man sagen, dass eine gute Dokumentation uns viel helfen kann. Ob der Entwickler sein Werk dokumentieren will, ist seine Entscheidung. Wir, die Benutzer, sollten die Doku aber unbedingt lesen, umso mehr wenn der Entwickler keine Zeit und Mühe gescheut eine gute Doku zu liefern ... Ihr wisst ja, für was die Abkürzung RTFM steht ;-)

Das Original dieses Artikels wurde von Mike Veekmans verfasst und erschien im Joomla! Community Magazine August 2013