Niemals das glamouröseste aller Themen. Dennoch kann eine qualitativ hochwertige interne Dokumentation für Entwicklungsteams ein Motor für Effizienz sein. Eine gute Dokumentation ist oft ein Zeichen für ein gesundes Entwicklungsteam, das stolz auf seine Arbeit ist. Langfristig wirkt sie sich positiv auf die Produktivität des Teams aus, da sie den Engpass um einzelne Personen, die viel Wissen über das System haben, beseitigt. Oft gibt es ein Teammitglied, das einen Grossteil seiner Zeit damit verbringt, anderen zu helfen, die Funktionsweise der Anwendung oder die Gründe für bestimmte Vorgehensweisen zu verstehen. Was passiert, wenn diese Person in ein anderes Team wechselt oder gar das Unternehmen verlässt?

In einer idealen Welt ist der Code selbstdokumentierend und leicht zu verstehen. Das ist das Argument, das Entwickler oft vorbringen, wenn sie gebeten werden eine Dokumentation zu schreiben. In der realen Welt ist dies jedoch selten der Fall:

• Der Code ist oft zu komplex, um ihn durch einfaches Lesen zu verstehen.
• Legacy-Code wurde möglicherweise nicht nach denselben Standards wie neuer Code geschrieben oder hat sich im Laufe der Zeit verschlechtert.
• Konzepte können über mehrere Dateien verteilt sein, was die Komplexität beim Versuch, sie zu verstehen, erhöht.
• Die Gründe für nuancierte Entscheidungen, die während der Entwicklung getroffen wurden, gehen verloren, wie z. B. leistungsabhängige Implementierungen.

Die Dokumentation von Standards und Praktiken ist ebenso wichtig. Im Laufe der Zeit entscheiden sich Teams für bevorzugte Vorgehensweisen, sei es die Struktur einer Anwendung, Entwurfsmuster für bestimmte Probleme oder Bibliotheken zur Unterstützung von Prozessen. Solche Entscheidungen sollten dokumentiert werden und leicht auffindbar sein, damit die Ingenieure schon früh im Entwicklungsprozess die richtigen Entscheidungen treffen können. Wenn bei der Codeüberprüfung festgestellt wird, dass etwas nicht den Teamstandards entspricht, ist das ineffizient und eine Verschwendung von Entwicklungszeit. Darüber hinaus ist es wichtig, dass die Teammitglieder mit einem gewissen Grad an Unabhängigkeit arbeiten können, insbesondere in der Welt des hybriden Arbeitens, in der sich ein kurzes Gespräch mit dem Kollegen in ein Telefonat verwandelt hat und daher den Arbeitsablauf beider Personen stärker stört.

Bei der Erstellung von Dokumentationen ist es wichtig, dass alle Beteiligten, unabhängig von ihrer Erfahrung, daran mitwirken können. Wenn nur erfahrene Ingenieure einen Beitrag leisten, könnten Details für jüngere Teammitglieder zu komplex sein oder einen Wissensstand voraussetzen, den vielleicht noch nicht alle Leser erreicht haben. Jeder sollte ermutigt werden, seine Wissenslücken zu schliessen.

Wie kann dies erreicht werden? Machen Sie die Dokumentation zu einem Teil des Entwicklungsprozesses. Gehört die Dokumentation zur "Definition of Done" des Teams? Kann für jede Pull-Request eine Aufgabe erstellt werden, um den Autor zu ermutigen, Änderungen vorzunehmen? Stellen Sie bei jeder Änderung die folgenden Fragen:

• Gibt es eine neue Funktion, von der andere wissen sollten?
• Hat sich etwas an einer bereits dokumentierten Funktion geändert?
• Fehlen Informationen, die für die Entwicklung benötigt werden?
• Wurde eine wichtige Entscheidung getroffen, die mit anderen geteilt werden sollte?

Helfen wir unserem zukünftigen Ich!

Andrew Main, Senior Software Entwickler, INTEGRATE Informatik AG