Softwaredokumentation
Webprojekte sinnvoll dokumentieren
Die Dokumentation von Projekten, Quellcode und Anpassungen wird von den meisten Software-Entwicklern nur als lästige Pflicht angesehen. Hier bilden Webworker keine Ausnahme. Dabei kann eine fehlende oder fehlerhafte Dokumentation unangenehme Folgen haben.
Unbewusst und wider besseres Wissen werden täglich Milliarden Zeilen Quellcode niedergeschrieben, die niemals dokumentiert und erläutert werden. Meist sind die Zeitpläne bis zum Launch der Seiten oder des Produkts so eng, dass keine Zeit mehr für eine Dokumentation bleibt. Fehlende Erläuterungen für den Quellcode können durchaus auch zum Geschäftsmodell gehören.
Denn wer seine Arbeitszeit in die Entwicklung eines Templates für Wordpress & Co. gesteckt hat, besitzt kein gesteigertes Interesse daran, dass die Kunden selbst Anpassungen oder grundlegende Änderungen vornehmen.
Dokumentation ist ein Muss!
Zu wirklich jedem Softwareprojekt - und da bilden Webseiten, Stylesheets oder PHP-Funktionen keine Ausnahme - sollte eine Dokumentation gehören. Im Minimum rudimentäre Hinweise darauf, wieso gerade dieser Weg zur Lösung eines Problems gewählt wurde oder welche Funktion ein Codeblock exakt übernimmt, sparen bereits eine Menge Zeit.
Denn selbst wenn nur eine Person an den Quellen arbeitet, muss diese sich erst wieder in die Struktur des Codes hineindenken, bevor Änderungen gefahrlos und an den korrekten Stellen gemacht werden können. Und ohne Dokumentation werden Änderungen im Team zu einem reinen Glücksspiel.
Wer im Kundenauftrag handelt, steht schon aus juristischen Gründen vor der Aufgabe, seine Arbeit dokumentieren zu müssen. Eine neue Webseite, eine Erweiterung für einen Shop oder ein CMS oder auch nur das neue Kleid für einen Internetauftritt - aus Sicht von Juristen handelt es sich dabei schlicht um Produkte, die im Auftrag eines Kunden entstanden sind oder diesem verkauft wurden. Und was für Entwickler nur Code ist, stellt für Anwälte und Richter einen idealen Kriegsschauplatz rund um Fragen wie Gewährleistung, Haftung und sogar Verbraucherschutz dar.
Dabei hat sich in den vergangenen Jahrzehnten bei Gericht die Haltung durchgesetzt, dass "Software" stets immer auch aus einer Dokumentation besteht, die dem Kunden zugänglich sein muss. Gestritten wird in aller Regel im Einzelfall dabei jedoch um die Form dieser Dokumentation und ob sie ausreichend ist.
Konkrete Ergebnisse und Hinweise darauf, wie eine gute Dokumentation denn auszusehen hat, sind aus unzähligen Rechtsstreitigkeiten aber kaum zu ziehen. Im Gegensatz zu vielen anderen Bereichen aus den technischen Beschreibungen werden Sie bei der Softwaredokumentation keine genormten Hinweise finden, wie eine solche Dokumentation aussehen sollte. Die vor Jahrzehnten einmal verabschiedeten DIN-Normen wurden ersatzlos zurückgenommen. Damit haben die Buchstaben dieser veralteten Beschreibungen also maximal den Charakter einer ersten Handreichung.
Exakte Kundenvereinbarungen treffen!
Gerade weil sich nirgendwo exakt nachschlagen lässt, wie umfangreich eine Dokumentation sein sollte, sollte vor dem Beginn des Projekts geregelt sein, wie weitreichend die Pflichten zur Dokumentation gefasst werden. Standardfloskeln aus Vordrucken für Werkverträge lassen zu viel Konfliktpotenzial übrig, da dort meist nur geregelt ist, dass der Auftragnehmer eben auch seine Arbeiten dokumentiert.
Es ist empfehlenswert, hier präzise Formulierungen zu finden, in welcher Form dokumentiert werden darf. Je präziser Sie regeln, was der Auftraggeber von Ihnen erwartet, desto besser. Die meisten Webworker dürften über die Jahre die Erfahrung machen, dass der Wunsch der Ansprechpartner nach einer umfassenden Dokumentation im gleichen Maß ansteigt wie das Investitionsvolumen in das Projekt. Legen Sie also am besten vor der Auftragserteilung fest, wie Ihr Tätigkeitsbericht aussehen soll und wie die eigentliche Programmierung dokumentiert wird. Erwartet der Kunde eine ausgedruckte und ausführliche Aufstellung von Funktionen, Klassen oder Strukturen?
Benutzerhandbuch - eine andere Sicht auf dieselbe Sache
Die Dokumentation im Sinne einer Dokumentationspflicht bei der Softwareerstellung umfasst aber nicht notwendigerweise auch zugleich ein Handbuch für die Anwender, also die eigentlichen Nutzer des Systems. Die Dokumentation beschreibt eher den Aufbau des Produkts und lässt dessen Entstehung nachvollziehbar erscheinen.
Ein Dienstleister, der die Aufgabe erhält, den Quellcode (oder allgemeiner das Produkt) zu überarbeiten, wird damit in die Lage versetzt, die Aufgabe schneller zu erledigen, und vor allen Dingen davor bewahrt, einen Fehler zu begehen, der unter Umständen dazu führt, dass das gesamte System nicht mehr funktioniert. Auf der Seite der Auftraggeber hält sich aber immer auch die Meinung, dass zu einer Dokumentation das Benutzerhandbuch gehört. Klar ist: Wer ein Plug-in für ein CMS oder Shopsystem entwickelt und sich an den Endverbraucher wendet, sollte das Produkt mit einem Handbuch ausliefern.
Schon allein aus Interesse des Absatzes. Und natürlich genießt ein Anwenderbuch einer Standardsoftware, die an Endkunden verkauft wird, juristisch einen anderen Stellenwert als Anpassungen an ein Warenkorbsystem, die im Auftrag eines anderen Unternehmens entwickelt wurden.
Wünscht der Auftraggeber also auch eine Instruktion für die Nutzer des Systems, sollten Sie sich die Produktion dieser zusätzlichen Handreichung auch bezahlen lassen. Denn wenn Sie Ihre Arbeit dokumentiert haben, sind die konkreten Instruktionen ein zusätzlicher Service für die Endanwender. Diese Unterlagen könnte ja etwa auch der Auftraggeber in eigener Regie erstellen.
Nicht ausreichend- einfache Kommentare
Die einfachste und schnellste Form, den Quellcode zu dokumentieren, besteht im häufigen Gebrauch der in allen Skript- und Programmiersprachen vorgesehenen Kommentarfunktion. Das geht rasch von der Hand und strukturiert die Inhalte des Quellcodes.
Die größten Vorteile dieses Ansatzes liegen klar auf der Hand. Sie verlieren mit der Dokumentation kaum Zeit, wenn Sie die Kommentare direkt während der Entwicklung in den Quellcode schreiben. In der Praxis sind die Kommentare aber nur bedingt geeignet. Einerseits ist es damit kaum möglich, sich einen Gesamtüberblick über das Projekt zu verschaff en. Während der gemeinsamen Arbeit im Team lassen sich Kommentare durchaus sinnvoll nutzen, um auf Bereiche hinzuweisen, die einer Überarbeitung bedürfen.
Lediglich zur Dokumentation und Strukturierung von Theme- und Template-Dateien für Wordpress oder ähnliche Systeme dürften sich Inline-Kommentare als ausschließliches Dokument eignen. Beim Schreiben sollten Sie auch daran denken, dass es mithilfe der Dokumentation jederzeit möglich sein sollte, einem Kollegen oder neuen Mitarbeiter die Zusammenhänge im Projekt zu erläutern. Mit Kommentaren im Quellcode können Sie etwa darauf hinweisen, dass auf den nächsten Zeilen eine Variable definiert wird. Aber den Zusammenhang mit anderen Variablen zu beschreiben, wird damit genauso schwierig, wie Sie auch auf grafische Definitionenverzichten müssen.
Beliebt und verbreitet: Doxygen
Beim Thema Dokumentation stehen sich verschiedene Sichtweisen und Ansätze gegenüber. Die Entwickler wollen in möglichst kurzer Zeit und mit wenig Aufwand die Dokumentation abschließen. Die Kunden legen dagegen auf eine möglichst ausführliche Beschreibung Wert, die keine Fragen aufkommen lassen sollte.
Die Durchsicht der Dokumentation sollte dabei ebenfalls möglichst wenig Zeit rauben, der Leser sich also möglichst schnell im Quelltext und in den Erläuterungen zurechtfinden. Doxygen wird bereits seit längerer Zeit entwickelt. Mit der Anwendung schreiben Sie die Erläuterungen, aus denen sich später die Dokumentation zusammensetzen soll, direkt in den Quelltext ein. Bei der Erstellung der Beschreibung arbeitet die Software ähnlich wie ein Compiler bei der Entwicklung. Dem Programm wird der Quelltext übergeben.
Tools zur Dokumentation
Zusätzlich werden einige weitere Textdokumente ausgewertet, die wichtige Parameter enthalten. Dazu gehören Vorgaben für Überschriften, Kopf- oder Fußzeilen, eventuell zu benutzende Grafiken sowie die Beschreibung des Layouts. Aus allen diesen Informationen kann Doxygen Dokumente in einer Reihe unterschiedlicher Zielformate anlegen. Unterstützt werden XML-Dateien, Dokumente in LaTeX und RTF-Dateien. Gerade über dieses Format können die Erläuterungen dann auch in bekannte Textverarbeitungen importiert werden. Unmittelbar unterstützt Doxygen die Quellcode-Formate C, C++, C#, IDL, Java, PHP und Python. Über Ergänzungen an den Steuerungsdateien ist aber auch die Anpassung an weitere Programmiersprachen möglich.
Nach dem gleichen Prinzip arbeiten auch noch eine Reihe weiterer Anwendungen, die sich für verschiedene Programmiersprachen eignen und unterschiedliche Ausgabeformate unterstützen.
Schnell zum Anwenderhandbuch
Die Dokumentation von Quelltexten aller Art ist eher eine Domäne von mehr oder weniger ausführlichen Texten. Standardisierte Diagramme (z. B. UML) helfen professionellen Anwendern beim Verständnis der Zusammenhänge. Die Nutzer einer Extension,einer Webseite oder eines Programms haben dagegen das Interesse, möglichst schnell damit arbeiten zu können.
Hier können Bilder ihre ganze Macht ausspielen, unter der Prämisse jedenfalls, dass sich die Oberfläche des Produkts nicht permanent ändert. Screencasts (also abgefilmte Abläufe auf dem Bildschirm) sind, wenn Sie denn zusätzlich mit Ton oder bildlichen Erläuterungen versehen wurden, eine sehr gute Möglichkeit, um Anwender an die ersten Schritte in einer neuen Umgebung heranzuführen.
Business Intelligence als Chefsache
Kommt es aber auf das gezielte Nachschlagen an, geht nichts über eine linear strukturierte, geschriebene Dokumentation, egal ob offline oder online. Mit der Beschreibung des Quellcodes hat sie gemeinsam, dass auch bei ihrer Herstellung ein möglichst geringer Aufwand betrieben werden sollte. Zur Lösung dieser Aufgabe können Entwickler auf verschiedene Werkzeuge zugreifen.
ScreenSteps: so lautet der Name einer Plattform, auf der sich im Team gemeinsam Benutzerhandbücher und Dokumentationen erstellen lassen. Grundlage bildet dabei eine Software, die sowohl für Windows als auch Mac angeboten wird. Das Programm fertigt in regelmäßigen Intervallen oder auch vollständig manuell Bildschirmfotos an.
Die Aufnahmen werden dann einfach mit vorgefertigten Symbolen oder auch Kennzeichnungen versehen, mit denen auf besondere Bereiche hingewiesen wird. Jeder Screenshot wird dabei (jedenfalls den Voreinstellungen gemäß) zu einer einzelnen Seite in der Dokumentation. Auf diesen werden dann zusätzlich noch Texte hinterlegt. Sie können das Tool in einer kostenlosen Probephase testen. Danach werden monatliche Gebühren fällig. Wer ausschließlich allein an einer Dokumentation arbeitet, muss hierfür immerhin mit 129 US-Dollar pro Jahr rechnen.
Dr. Explain: nach einem ähnlichen Prinzip arbeitet Dr. Explain, das preislich in der gleichen Liga spielt, aber ausschließlich der Windows-Welt vorbehalten ist. Es kennt eine Reihe weiterer Ausgabeformate, etwa das für Windows typische CHM-Format der Hilfedateien, muss aber auf die Möglichkeit der Online-Zusammenarbeit verzichten. Auch für dieses Produkt steht eine Demoversion zur Verfügung.
Dank zahlreicher Anwendungen hat das Thema Softwaredokumentation viel von seinem Schrecken verloren. Die Programme für die Beschreibung der Quellen erwarten von den Anwendern aber zunächst Arbeit in der Zusammenstellung der Arbeitsumgebung und Einarbeitung in die Syntax. Dies gilt auch sinngemäß für die Tools, mit denen sich die Anwenderdokumente generieren lassen. Dank der grafischen Oberflächen ist der Aufwand für die Einarbeitung in diese Tools gering. Zumeist werden unabhängig davon ohnehin kaum alle Möglichkeiten ausgeschöpft, die in den Anwendungen enthalten sind.
