Dokumentation

Eine wichtige Maßnahme zur nachhaltigen Gestaltung eures Software-Projekts ist eine öffentliche Dokumentation, die es potenziellen Mit-Entwickler*innen und Nutzenden einfach macht, euer Projekt zu nutzen, dazu beizutragen oder weiterzuentwickeln. Deswegen möchten wir alle Projekte beim Prototype Fund ermutigen und dabei unterstützen, Zeit in den Aufbau ihrer Dokumentation zu investieren. Sollte euer Projekt eine Second-Stage-Förderung erhalten, ist die ausführliche Dokumentation Pflicht, um die Nachhaltigkeit des Projektes zu stärken. Daher muss am Ende der Förderzeit für alle Projekte der Second Stage eine öffentlich verfügbare Dokumentation im Schlussbericht verlinkt sein.

Je nach Projekt kann die Art der Dokumentation unterschiedlich sein. Während der Code eines Projekts immer sauber dokumentiert sein sollte, sind zusätzliche Dokumentationsmaßnahmen abhängig vom Projekt und der Zielgruppe: unterschiedliche Formate von Tutorials für Endnutzer*innen, Admin-Dokumentation für selbstgehostete Projekte, Entwickler*innendokumentation für Libraries und andere Infrastrukturprojekte usw. Welche Arten von Dokumentation am Ende eures Projekts veröffentlicht sein sollten, wird sehr unterschiedlich sein. Generell gilt: Ihr wisst, wer eure Zielgruppe ist und wie sie eure Software nutzen möchte. Danach sollte sich die Doku entsprechend richten. Gerne könnt ihr eure Coachings oder Zwischengespräche nutzen, um gemeinsam zu überlegen, was in eurem Fall sinnvoll ist. Auf dieser Seite wollen wir zudem einen groben Überblick geben, was nach unserem Verständnis zu guter Dokumentation gehört.

Arten von Software-Dokumentation Es gibt keine offiziellen Standards, wie gute Dokumentation aussieht und was sie beinhalten sollte. Die von uns aufgezählten Formen von Dokumentation lassen sich entsprechend auch nicht klar voneinander abgrenzen und überschneiden sich in manchen Fällen. Code-Kommentare Kommentare im Code nutzt ihr höchstwahrscheinlich sowieso, um eure Arbeit für euch und andere verständlicher zu machen. So wichtig diese Kommentierungen sind, um den Code verstehen und nachvollziehen zu können, sollten sie natürlich nicht die einzige Form von Dokumentation sein, die euer Projekt hat.

Technische Dokumentation Die technische Dokumentation ist ein weites Feld, die Informationen über die technischen Aspekte der Software sowohl für (Mit-)Entwickler*innen, als auch für Endnutzer*innen enthalten kann. Das können zum Beispiel Informationen zum technischen Design, Projektpläne und Angaben zu Spezifikationen und Anforderungen sein. Dokumentation der Architektur und Referenzmaterialien (Doku von APIs oder Datenmodellen) können Teil der Dokumentation sein, ebenso wie Benutzendenhandbücher, die Nutzungsmöglichkeiten und Features zur effektiven Nutzung dokumentieren oder Troubleshooting-Guides bei bekannten Problemen.

Nutzenden-Dokumentation Über die technische Dokumentation hinaus sollte es, wenn Endnutzer*innen Teil eurer Zielgruppe sind, weitere Dokumentation zum einfachen Verständnis und zur Nutzung der Software geben. Das kann zum Beispiel in Form von How-to- und Quick-Start-Guides, Release Notes oder Tutorials sein, die als Teil von Readmes, Handbüchern, Wikis oder in Videoform vorliegen.

Community-Contributions-Dokumentation Wenn ihr vorhabt, eine Community rund um euer Projekt aufzubauen, die gemeinsam mit euch entwickelt und Beiträge in verschiedensten Formen leisten soll, ist Dokumentation dafür unerlässlich. Potenzielle Interessierte brauchen gute technische und Nutzenden-Dokumentation, um eure Ideen, Prozesse und Pläne für das Projekt zu verstehen. Insbesondere Entwicklungs-, Release- und Testingpläne helfen für ein tieferes Verständnis des Entwicklungsprozesses, ebenso wie Bug-Tracking-Reports. Wenn ihr euch Contributions von der Community wünscht, sind außerdem ein Code of Conduct sowie ein Contributions-Guide hilfreich, um zu erklären, was für Unterstützung ihr sucht und wie der Prozess und die Zusammenarbeit idealerweise aussehen sollten.

“Nicht offiziell Dokumentation, aber…”? Neben der offiziellen Dokumentation sind oft weitere Ressourcen rund um das Projekt relevant, wie etwa Forendiskussionen. Auch wenn es sich primär um Community-Plattformen handelt: Dadurch, dass diese Q&A-Formate (im Gegensatz zu Community Calls oder Chatgruppen/Channels) öffentlich einsehbar und durchsuchbar sind, bilden sie hilfreiche Ressourcen für Nutzende und Beitragende. (Achtung, dieses Format ersetzt keine strukturierte Dokumentation - es ist aber interessant als communityfreundliche Zusatzmaßnahme.)