Dokumentation

(English version below)

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.)

Welche Dokumentation ist für mein Projekt relevant?

Bei der Entscheidung, welche Dokumentation in eurem Fall sinnvoll ist, spielen verschiedene Faktoren eine Rolle, unter anderem die Zielgruppen des Projekts und deren Bedürfnisse, die Kanäle, auf denen ihr über das Projekt informiert usw. Wenn ihr euch unsicher seid, was ihr anbieten wollt, bzw. generell Unterstützung beim Erstellen von Dokumentation sucht, empfehlen wir euch ein Coaching zu dem Thema. Natürlich könnt ihr euch bei Fragen auch immer bei der Projektbetreuung melden.

Ressourcen für gute Code-Dokumentation findet ihr außerdem in der Knowledge Base.

Documentation

An important part of making your software project sustainable is having public documentation that makes it easy for potential co-developers and users to engage with, contribute to, or further develop your project. That's why we encourage and support all Prototype Fund projects to invest time in building their documentation.

If your project receives funding in the Second Stage, detailed documentation is mandatory in order to strengthen the sustainability of the project. Therefore, at the end of the funding period, all Second Stage projects must include a link to publicly available documentation in their final report.

The type of documentation can vary depending on the project. While the code of a project should always be clearly documented, additional documentation measures depend on the project and the target audience: different formats of tutorials for end users, admin documentation for self-hosted projects, developer documentation for libraries and other infrastructure projects, etc.

The types of documentation you should publish at the end of your project are likely to vary greatly. In general, you know who your target audience is and how they want to use your software. The documentation should be tailored accordingly. Feel free to use your coaching sessions or 1:1 meetings to discuss what makes sense in your case. On this page, we also want to give a rough overview of what we believe constitutes good documentation.

Types of software documentation

There are no official standards for what good documentation looks like and what it should contain. The forms of documentation we have listed cannot be clearly distinguished from one another and overlap in some cases.

Code comments

Most likely, you use comments in the code anyway to make your work more comprehensible for yourself and others. As important as these comments are for understanding and following the code, they should not be the only form of documentation your project has.

Technical documentation

Technical documentation is a broad field that can contain information about the technical aspects of the software for both (co-)developers and end users. This can include information on technical design, project plans, and details on specifications and requirements. Documentation of the architecture and reference materials (documentation of APIs or data models) can be part of the documentation, as can user manuals that document possible uses and features for effective use, or troubleshooting guides for known problems.

User documentation

Beyond technical documentation, if end users are part of your target audience, there should be additional documentation to help them easily understand and use the software. This can take the form of how-to and quick-start guides, release notes, or tutorials that are available as part of readmes, manuals, wikis, or in video form.

Community contributions documentation

If you plan to build a community around your project and want them to develop together with you and contribute in various ways, documentation is essential. Potential contributors need good technical and user documentation to understand your ideas, processes, and plans for the project. Development, release, and testing plans are particularly helpful for a deeper understanding of the development process, as are bug tracking reports. If you want contributions from the community, a Code of Conduct and a Contributions Guide are also helpful in explaining what kind of support you are looking for and what the process and collaboration should ideally look like.

“Not official documentation, but...”?

In addition to the official documentation, other resources related to the project, such as forum discussions, are often relevant. Even if these are primarily community platforms: the fact that these Q&A formats (unlike community calls or chat groups/channels) are publicly viewable and searchable makes them helpful resources for users and contributors.

(Note that this format is not a substitute for structured documentation, but it is an interesting community-friendly addition.)

Which documentation is relevant for my project?

When deciding which documentation is suitable for your case, various factors play a role, including the target groups of the project and their needs, the channels through which you provide information about the project, etc. If you are unsure about what you want to offer or are looking for general support in creating documentation, we recommend taking a coaching session on the topic. Of course, you can always contact the program management team if you have any questions.

Resources for good code documentation can also be found in the Knowledge Base.