Websites sind Software und somit ein Produkt, was zwansgweise ständigem Wandel unterworfen ist. Sei es weil Websites immer wieder aktualisiert werden oder weil neue Seiten und Inhalte hinzukommen. Während ein CMS wie WordPress oder TYPO3 das Anlegen neuer Seiten und die Erweiterung des Seitensbaums ohne Programmierkenntnisse möglich macht, muss man manchmal auch Änderungen am Website Code vornehmen.
Wann lohnt sich die Website Dokumentation
Ab dem Zeitpunkt, wo Hand am Code angelegt werden muss, zahlt es sich aus, dass Code gut dokumentiert wurde. Auch wenn der Auftraggeber im besten Fall die Dokumentation der Website nie zu Gesicht bekommt, kann er trotzdem eine Menge Zeit und Geld sparen. Hierfür gibt es gleich mehrere Szenarien:
Ein anderer Programmierer übernimmt den Code
Häufig – vor allem bei Entwicklerstudios oder Agenturen – kommt es vor, dass der Webentwickler, der die Seite programmiert hat, nicht mehr zur Verfügung steht. Da jeder Entwickler seinen eigenen Stil hat und einige CMS wie WordPress auch relativ viele Freiheiten bei der Herangehensweise lassen, ist eine gute Dokumentation hilfreich. Sie hilft dem neuen Programmierer, sich in die Struktur und die grundlegende Logik der Seite einzuarbeiten.
Die letzte Aktualisierung ist bereits eine Weile her
Dabei muss es nicht immer gleich ein neuer Programmierer sein. Wir schreiben nicht umsonst Rezepte auf und tragen Termine in einen Kalender ein. Menschen vergessen Dinge mit der Zeit, und gerade wenn einige Zeit vergangen ist, kann es nicht schaden nochmal die Gedankengänge der Programmierung nachvollziehen zu können. Denn auch wenn der Programmierstil gleich geblieben ist: Standards können sich mit der Zeit ändern und frühere Tools wurden dann schon lange nicht mehr verwendet.
Alternative Entwicklungsansätze
Lösungswege für bestimmte Probleme auf Websites haben immer verschiedene Vor- und Nachteile. Manchmal muss während der Entwicklung erprobt werden, welche Lösung für den Kunden die beste ist. Wenn dann eine Entscheidung getroffen wird, kann eine gute Dokumentation Code besser strukturieren. Es wird ersichtlicher, welche Codeteile benötigt werden, und welche gestrichen werden können.
Welche Möglichkeiten der
Website Dokumentation gibt es?
Welche Möglichkeiten der Dokumentation gibt es? Es gibt verschiedene Methoden, Code zu dokumentieren. Je nach Komplexität des Webprojekts, ergeben verschiedene Methoden dabei mehr oder weniger Sinn.
Codedokumentation
Die Ausgabe von Inhalten auf der Website erfordert immer Funktionen. Je nachdem, wie komplex diese Anforderungen sind, können auch die Funktionen selber am Komplexität zunehmen, oder sogar in mehrere Teilschritte unterteilt werden.
/**
* Recieves the test data and calculates the results
* Return the results, and if the user has passed
*
* @param Test $test
*
* @throws \TYPO3\CMS\Extbase\Mvc\Exception\NoSuchArgumentException
* @throws \TYPO3\CMS\Extbase\Persistence\Exception\IllegalObjectTypeException
*/
public function resultAction( Test $test )
{
$result = new Result( $test );
return $result;
}Eine Methode oder Funktion dokumentiert man auf verschiedene Weisen. So findet sich ein anderer Programmierer bei der Einarbeitung besser zurecht.
Hier gibt es verschiedene Möglichkeiten, den Code gut wartbar zu schreiben. Zum einen sollte man ohnehin auf guten Code achten. Das bedeutet, dass man eine Idee davon hat, wie man Funktionen, Variablen oder Klassen nennt und diese Regeln auch konsequent verwendet. Zum anderen können die Methoden selber auch aber auch mit einer Codedokumentation versehen werden. So weiß der Programmierer, was eine Funktion mit welchen Werten macht und wie sie diese zurückgibt. Solche Hilfen heißen dann je nach Sprache z.B. PHPDoc oder JavaDoc.
Skript Dokumentation
Man arbeitet selten direkt an der Website. Der Programmierer hat meistens eine lokale Version der Website, an der er erst den Code schreibt, und in einem zweiten Schritt die fertige Version auf die eigentliche Domain hochlädt.
Man legt man in der Regel eine README.md an, Damit der Programmierer weiß, wie er die Website lokal anlegen kann, und wie die Website zu Laufen gebracht werden kann. Hier findet sich im besten Fall eine Anleitung zum Start der Website
Externe Dokumentation
Meistens reicht eine reine Codedokumentation nicht aus, wenn Ihre Website komplexe Funktionen hat oder sie in einem Team entwickelt wird. Eine Codedokumentation zeigt nämlich meistens nur den Ist-Stand an einer bestimmten Stelle des Codes. Das große Ganze, die Konzeption der Logik der Website kann hier nicht übersichtlich dargestellt werden.
Hier lohnt es sich auf jeden Fall, Datenbanken, Prozesse oder Abhängigkeiten von Drittanbietern übersichtlich in Form von Texten oder Schaugrafiken abzubilden. Das hilft nicht nur bei der Konzeption, sondern auch bei der Übergabe einer Software oder beim erneuten „Reindenken“.
Warum erstellt man Website Dokumentation so selten?
Trotz aller Vorteile übernehme ich nur selten Webprojekte, die eine gute Dokumentation vorweisen. Woran liegt das? Sicher ist Bequemlichkeit ein Faktor. Dokumentation passiert nicht von alleine, sondern ist ein zusätzlicher Arbeitsschritt.
Das größte Problem ist meinen Augen jedoch, dass Auftragsarbeiten im Webbereich (und vermutlich auch in anderen Bereichen) immer so schnell wie möglich fertig werden müssen.
Wenn weder Budget, noch Zeit vorhanden ist, ist die Dokumentation das erste, was unten wegfällt. Einen Gefallen tut sich der Auftraggeber damit nicht. Probleme und Fehler die zum Beispiel erst nach einigen Monaten auftauchen, sind dann nur schwer im Code zu finden. Nach hinten raus kann der Aufwand, der durch fehlende Dokumentation entsteht also sogar höher sein.
Die Frage bleibt aber am Ende, was eine ordentliche Dokumentation kosten sollte. Mein Erfahrungswert ist, dass je nach Art der Dokumentation der Programmieraufwand um 10-20% steigt, entsprechend biete ich bei meinen Angeboten eine entsprechende Option, die sich auf Grundlage der veranschlagten Programmierstunden orientiert.
