Die Entwickler-Dokumentation
Die Entwickler-Dokumentation ist neben dem Benutzerhandbuch das wichtigste Dokument einer Software und in vielen Fällen der Dreh- und Angelpunkt für deren Erfolg. Denn für die meisten EntwicklerInnen dürfte das Lesen einer Entwickler-Dokumentation zur täglichen Praxis gehören. Der Grund liegt im Wesen moderner Software-Entwicklung: Fast nie arbeitet man von Grund auf mit dem eigenen Code. Stattdessen werden bestehende Frameworks verwendet, Erweiterungen geschrieben, Bibliotheken eingebunden, APIs angesprochen und SDKs genutzt. Ist die jeweilige Software oder Schnittstelle schlecht dokumentiert, erschwert das die Arbeit von EntwicklerInnen erheblich. Grund genug, im Wettbewerb um die Gunst der EntwicklerInnen etwas Arbeit in eine gute Entwickler-Dokumentation zu investieren.
- Die Entwickler-Dokumentation
Schritte zu einer guten Entwickler-Dokumentation
Bei der Erstellung einer Software-Dokumentation kann man sich an ein paar Schritten orientieren:
- Die Zielgruppe analysieren.
- Die Ziele für die Entwickler-Dokumentation festlegen.
- Ein passendes Layout wählen.
- Die inhaltlichen Bausteine für die Dokumentation konzipieren.
- Die passenden Tools auswählen.
Zielgruppe für die Entwickler-Dokumentation analysieren
Zielgruppe einer Entwickler-Dokumentation sind natürlich in erster Linie die EntwicklerInnen. Deren Kenntnisstand reicht allerdings vom Einsteiger- bis zum Profi-Level. Außerdem gibt es die unterschiedlichsten Spezialisierungen, vom DevOps bis hin zur Frontend-Entwicklung.
In vielen Fällen gibt es neben der Kern-Zielgruppe auch noch weitere Zielgruppen, die nicht unbedingt einen technischen Hintergrund haben. Beispielsweise werden die Versionierungssoftware Git und die Plattform GitHub auch von Textern, Designern und anderen Berufszweigen genutzt. Die Dokumentation für ein Frontend-Framework dürften hin und wieder auch von Designern und Produktmanagern gelesen werden. Und Dokumentationen für APIs und OnPremise-Software wird zur groben Orientierung auch von ProjektmanagerInnen oder anderen Rollen im technischen Umfeld benutzt. Je nach Ausrichtung der Software sollte man bei der Dokumentation solche Zielgruppen im Auge behalten.
Eine gute Entwickler-Dokumentation sollte allen Zielgruppen die Möglichkeit bieten, die benötigten Informationen schnell zu finden und praktisch zu nutzen. Daher ergeben sich aus der Zielgruppen-Analyse bereits einige Vorüberlegungen:
- Wie sind die Zielgruppen gewichtet?
- Gibt es unterschiedliche Zielgruppen, die in der Dokumentation ggf. getrennt angesprochen werden können?
- Wie kann ich den unterschiedlichen Kentnisstand verschiedener Zielgruppen bedienen?
Konkret kann die Zielgruppen-Analyse in der Trennung einzelner Dokumentations-Bereiche führen, beispielsweise in sprachspezifischen Bereichen (zum Beispiel bei SDKs), in verschiedene Guides und Tutorials für unterschiedliche Nutzergruppen, in Schnell-Start-Blöcken für Profis und Detail-Beschreibungen für Einsteiger, in Code-Referenzen und Schritt-für-Schritt-Anleitungen.
Ziele für die Entwickler-Dokumentation definieren
Die Zielgruppen-Analyse bietet einen guten Rahmen, um die Ziele der Entwickler-Dokumentation festzulegen. Grundsätzlich soll die Entwickler-Dokumentation die Zielgruppen bei der Nutzung und Implementierung einer Software durch gut strukturierte und praxisnahe Informationen unterstützen, sodass die EntwicklerInnen oder NutzerInnen möglichst gerne und effektiv mit der Software arbeiten.
Im Detail kann es jedoch eine große Bandbreite bei den Zielen geben. Als Beispiel:
- Die Software positioniert sich als einfache Alternative im Markt. Die Entwickler-Dokumentation soll diesen Charakter mit einer möglichst simplen Gestaltung, einer einfachen Struktur und wenigen, sofort nutzbaren Code-Beispielen widerspiegeln.
- Die Software positioniert sich als feature-mächtiges Enterprise-Tool. Die Entwickler-Dokumentation soll einen einfachen Einstieg bieten, darüber hinaus jedoch den Feature-Reichtum und die Detail-Tiefe repräsentieren.
Damit wird auch klar, dass eine Entwickler-Dokumentation nicht nur informations-basiert ist, sondern auch ein zentrale und strategische Rolle bei der Positionierung und Verbreitung einer Software spielt. Das kann sich auch in der Sprache der Dokumentation widerspiegeln. Ziel ist immer, die EntwicklerInnen möglichst gut bei der Nutzung und Implementierung der Software zu unterstützen. Dabei muss man die EntwickerInnen jedoch nicht langweilen. Und es ist auch erlaubt, die Vorzüge der Software herauszuarbeiten.
Ein Layout für die Entwickler-Dokumentation wählen
Für Entwickler-Dokumentationen haben sich zweispaltige und dreispaltige Layouts etabliert. In der linken Spalte befindet sich eine Navigation. In der rechten Spalte findet man die Erläuterungen mit den Code-Beispielen. Alternativ werden die Code-Beispiele in eine dritte Spalte ausgelagert.
Zweispaltige Dokumentations-Layouts
Zweispaltige Layouts haben den Vorteil, dass sie sehr klar und einfach wirken. Nicht nur kleine Software-Projekte bevorzugen daher zweispaltige Layouts, sondern auch größere Platformen wie Mailchimp. Das reduzierte Layout vermittelt den Eindruck einer einfachen Handhabung und einer schnellen Integration.
Dreispaltige Dokumentations-Layouts
Das dreispaltige Layout wurde vor allem durch Stripe populär. Der Vorteil ist der schnelle Einstieg in den Code. Wenn der Code selbsterklärend ist, können erfahrene EntwicklerInnen die Erläuterungen übergehen und sich direkt aus der Dokumentation ihre Integration zusammenkopieren.
Layout-Kombinationen
Es gibt auch Kombinationen aus beiden Varianten. GitHub nutzt beispielsweise für eher textlastige Einführungdn ein zweispaltiges Layout und integriert kurze Code-Beispiele in den Text. Die dritte Spalte wird für eine Überschriften-Navigation verwendet. Für code-lastige Seiten verwendet auch GitHub ein dreispaltiges Layout ähnlich wie Stripe.
Navigationselemente
Die meisten Entwickler-Dokumentation bieten eine hierarchisch gegliederte, vollständige und immer präsente Navigation in der linken Spalte eines zwei- oder dreispaltigen Layouts an. So kann der Nutzer die gesamte Inhaltsstruktur erfassen und leicht navigieren.
Es gibt natürlich auch Abweichungen von diesem Prinzip, zum Beispiel Zielgruppen-orientierte Einstiege, bei denen die Navigation eingeschränkt wird oder man zum Beispiel durch Kachel-Elemente durch die Navigation springt. Bei solchen Variationen sollte man allerdings aufpassen, dass die Orientierung nicht leidet.
Bei den meisten Dokumentationen findet man noch weitere Navigationselemente:
- Eine Breadcrumb-Navigation.
- Eine Vor- und Zurück-Navigation.
- Eine Versions-Auswahl.
- Eine Suche.
- Eine Sprung-Navigation zu den Überschriften der Seite.
- Edit-Button, zum Beispiel zur Bearbeitung einer Seite im GitHub-Repository.
- Übliche Header- und Footer-Navigationen.
Inhaltliche Bausteine konzipieren
Je nach Ausrichtung können Entwickler-Dokumentationen unterschiedliche Bausteine haben. Standard-Elemente sind eine Einführung ("Getting-Started", Schritt-für-Schritt-Anleitungen und Code-Referenzen. Darüber hinaus kann man auf eine recht große Palette an inhaltlichen Bausteinen zurückgreifen.
Getting Started
Die meisten Dokumentationen bieten einen Einstiegs-Bereich, häufig unter dem Stichwort "Getting Started". Dieser Abschnitt soll als eine Art Schnellstartanleitung dienen, die es Entwicklern ermöglicht, mit minimalen Vorbereitungen einen Einstieg in die Software zu finden. Ziel ist es, dem Nutzer ein Erfolgserlebnis zu verschaffen und ihn dazu zu motivieren, tiefer in die Materie einzusteigen.
Welche Punkte unter "Getting Started" abgehandelt werden, hängt auch davon ab, ob es sich beispielsweise um eine OnPremise-Software, um eine SaaS-Software, um eine API oder um eine SDK handelt.
Bei einer OnPremise-Software ist die erfolgreiche Installation und die erste Nutzung der Software das Ziel einer Getting-Started-Beschreibung. Dazu muss der Nutzer zum Beispiel die Systemvoraussetzungen und die Installationsschritte kennen. Bei einer SaaS-Lösung oder einer API ist meist die Installation einer SDK, die Authentifizierung und ein erster API-Call das Ziel. Oft werden unter Getting Started auch grundlegende Abläufe in einer Schritt-für-Schritt-Anleitung durchgespielt und auf weitere Details verlinkt.
Core-Concepts und das Gesamtbild
Unter Überschriften wie "Core-Concepts" oder "Basics" werden grundlegende Konzepte einer Software erklärt. Das Grundlagenwissen soll Entwicklern einen Rahmen geben, innerhalb dessen sie die spezifischen Funktionen und Möglichkeiten der Software verstehen können. Die Erklärung von Core-Concepts sollte so gestaltet sein, dass sie Entwicklern hilft, die Philosophie hinter der Software, ihre Architektur und ihre Designentscheidungen nachzuvollziehen. Dies kann das Lernen erleichtern und Entwicklern ermöglichen, fundiertere Entscheidungen zu treffen, wenn sie die Software nutzen oder erweitern.
Die Erläuterung der grundlegenden Konzepte ist jedoch keine Pflichtübung und muss nicht unbedingt Bestandteil einer Entwickler-Dokumentation sein. Eine Gefahr besteht darin, EntwicklerInnen mit komplexen Informationen abzuschrecken, die für die Nutzung der Software nicht unbedingt relevant sind. Sinnvoll ist die Darstellung von Core-Konzepten vor allem, wenn sie das Verständnis von darauf aufbauenden Anleitungen und Guides erleichtern.
Schritt für Schritt Anleitungen
Schritt für Schritt Anleitungen sind nicht nur ein wichtiges Element für Benutzerhandbücher, sondern spielen auch bei Entwickler-Dokumentationen eine große Rolle. Ein Beispiel dafür bietet der Payment-Dienstleister Paddle. Die Dokumentation besteht zum überwiegenden Teil aus prozessualen Darstellungen mit Checklisten und detaillierten Schritt-für-Schritt-Anleitungen. Die Code-Beispiele werden dabei in die Anleitungen integriert. Die dritte Spalte nutzt Paddle für eine Sprung-Navigation.
Während Paddle die Entwickler-Dokumentation fast vollständig mit Schritt für Schritt Anleitungen aufbaut, werden solche Prozess-orientierten Beschreibungen häufig auch separat als Guides, Tutorials oder Cookbooks angeboten.
Guides, Tutorials und Cookbooks
Die Bausteine "Guides", "Tutorials" und "Cookbooks" bestehen überwiegend aus Schritt-für-Schritt-Anleitungen und unterscheiden sich lediglich in Ausrichtung und Zielsetzung: Guides dienen dem Aufbau eines umfassenden Verständnisses, Tutorials dem Erlernen durch praktische Anwendung, und Cookbooks dem schnellen Zugriff auf Lösungen für spezifische Probleme.
- Guides sind umfassende Anleitungen, die darauf abzielen, Nutzer durch komplexe Themen, Funktionen oder Workflows zu führen. Sie bieten einen detaillierten Einblick in bestimmte Aspekte der Software und sind oft strukturiert, um ein tiefes Verständnis zu fördern. Guides erklären Konzepte schrittweise und gehen auf Best Practices ein, um Nutzern zu helfen, die Software effektiv zu nutzen. Sie sind ideal für Nutzer, die sich mit den Prinzipien und der Philosophie hinter der Software vertraut machen möchten, und bieten eine solide Grundlage für fortgeschrittene Themen.
- Tutorials sind praxisorientierte Anleitungen, die darauf ausgelegt sind, Nutzern zu helfen, durch das Ausführen spezifischer Aufgaben oder Projekte etwas Bestimmtes zu lernen. Sie sind in der Regel schrittweise Anweisungen, die ein einzelnes Ziel oder Projekt von Anfang bis Ende durchgehen, und sie sind oft für Anfänger gedacht. Tutorials sind sehr hands-on und zielen darauf ab, dem Nutzer ein sofortiges Erfolgserlebnis zu verschaffen, indem sie ihn durch den Prozess der Erstellung eines Projekts oder der Durchführung einer Aufgabe führen.
- Cookbooks sind Sammlungen von "Rezepten", die Lösungen für spezifische, häufig auftretende Probleme oder Aufgaben bieten. Jedes "Rezept" in einem Cookbook beschreibt, wie man eine bestimmte Aufgabe löst oder ein spezifisches Problem angeht, oft durch eine kurze, punktuelle Anleitung. Cookbooks sind besonders wertvoll für erfahrene Nutzer, die nach schnellen Lösungen oder Best Practices für bestimmte Herausforderungen suchen.
Code-Referenzen
Code-Referenzen sind vollständige Kataloge der nutzbaren Entwickler-Schnittstellen einer Software. Sie werden häufig automatisch oder halbautomatisch erzeugt. Die Code-Referenzen enthalten beispielsweise alle verfügbaren Methoden, Funktionen und Klassen einer Schnittstelle oder sämtliche Endpunkte einer API. Die Referenzen sind untereinander verlinkt und enthalten die notwendigen Beschreibungen, damit die EntwicklerInnen die Schnittstelle nutzen können.
Referenzen werden häufig mit Schritt-für-Schritt-Anleitungen und anderen erläuternden Bereichen der Enwickler-Dokumentation verwoben. Gerade wenn die Code-Referenz von den erläuternden Teilen der Dokumentation getrennt ist, werden die LeserInnen durch solche Verlinkungen zum Springen zwischen den Bereichen verleitet. Dadurch kann bei Erläuterungen der roten Faden verloren gehen und bei den LeserInnen im schlimmsten Fall auch die gesamte Orientierung. Man sollte bei den Verweisen daher eine Balance oder eine Form finden, die den Nutzer nicht unnötig aus dem Lesefluss reist.
Troubleshooting
Nicht immer klappt der Umgang mit einer Software gleich beim ersten mal. Solche Frustrations-Momente können allerdings in vielen Fällen einen Absprung des Nutzers provozieren. Ein Klassiker ist die fehlgeschlagene Installation eines CMS. Ein alternatives CMS wartet nur wenige Klicks entfernt.
In solchen Momenten können gute Trouble-Shooting-Leitfänden helfen, die NutzerInnen mit einem Erfolgserlebnis wieder zurück zu holen. Ein guter Trouble-Shooting-Leitfaden zeichnet sich durch klare, leicht verständliche Anweisungen aus, die NutzerInnen schrittweise durch die gängigsten Probleme und deren Lösungen führen. Er sollte gut strukturiert sein, mit einer logischen Gliederung der Probleme nach Häufigkeit oder Thema, um NutzerInnen ein schnelles Auffinden relevanter Lösungen zu ermöglichen. Zudem ist es wichtig, dass der Leitfaden mit Beispielen, Screenshots oder Diagnosetools angereichert ist, um die Problembehebung zu vereinfachen und effektiver zu gestalten.
Changelog
Changelogs sind die zentrale Referenz und das Nachschlagewerk für Änderungen einer Software und sollten in einer Dokumentation nicht fehlen. Wichtig sind solche Changelogs vor allem, weil die Fülle an kleinen Änderungen über die üblichen Kanäle wie Blogs oder Newsletter nicht sinnvoll vermittelt werden könne, obwohl solche Details für EntwicklerInnen und AnwenderInnen oft entscheiden sind.
Changelogs werden meisten auf Basis von Git-Commits oder von Ticket-Systemen erstellt. Wenn das Repository oder das Ticket-System öffentlich sind, können die einzelnen Punkt des Changelogs auf die jeweiligen Commits oder Tickets verweisen. Damit wird eine vollständige Transparenz hergestellt.
Tipps für gute Inhalte
Neben den grundsätzlichen Inhalts-Blocks gibt es noch weitere Tipps für einzelne Inhalts-Elemente.
Code-Beispiele
Code-Beispiele sollten im besten Fall immer sofort nutzbar sein. Code-Beispiele haben einen Copy-Button zum Kopieren in die Zwischenablage. Code-Beispiele sind außerdem sprachspezifisch, sofern mehrere Sprachen nutzbar sind. Eingebürgert haben sich Tabs, mit denen man zwischen den Sprachen navigieren kann.
Stripe nutzt auch in diesem Bereich alle Möglichkeiten: Der Nutzer kann initial seine Architektur, seine Frontend-Sprache und seine Backend-Sprache auswählen und bekommt dann nur die relevanten Sprachen und die Variationen angezeigt. Neben dem Download-Button bietet Stripe auch noch einen Button zum Herunterladen der Code-Beispiele an. Wenn möglich bietet der Code auch noch eine gerenderte Vorschau des Ergebnisses an.
Sofort nutzbare Code-Beispiele sollte es für möglichst alle relevanten Anwendungsfälle geben. Für komplexere Authentifizierungsverfahren ebenso wie ein Datenbank-Schema, falls für die Integration der Aufbau einer eigenen Datenbank erforderlich ist. Wer den Nutzer dabei mit Text-Beschreibungen abspeist, erzeugt sehr viel Arbeit für Boilerplate-Code.
Interaktiver Code
Interaktiver Code ist vor allem bei APIs-Dokumentationen ein Thema. Hier gibt es viele Beispiele, wie EntwicklerInnen sehr schnell an einen API-Key gelangen und die Schnittstelle dann live in der Dokumentation testen können. Daneben können vor allem für Frontend-Themen recht einfach interaktive Elemente eingebaut werden. Stripe bietet für Frontend-Code beispielsweise eine Vorschau an, in dem die Code-Beispiele gerendert werden. Bei dem Frontend-Framework Vue gibt es einen Playground, mit dem Code-Beispiele getestet werden können.
Screenshots
Eine Kombination aus Bildern und Text sorgt dafür, dass LeserInnen nicht den Überblick verlieren. Zudem erleichtern GIFs das Verständnis und die Nachahmung von Abläufen. Screenshots sollten konsistent sein. Die Benutzeroberfläche sollte immer vom gleichen Betriebssystem und von derselben Version der Software stammen. Das Bild sollte außerdem zugeschnitten sein und zentrale Elemente hervorgehoben werden, sodass die LeserInnen nicht den Bildschirm nach den relevanten Informationen absuchen müssen. Für die Barrierefreiheit sind erforderlich.
Simple explainers
Creating good developer documentation requires empathy. Even when your readers are technical, they may not have the same skill set or knowledge base that you have. You’re steeped in your own codebase, in the use cases for your own product—readers will never know as much as you do. Take the time to break your product down for them. Doing so will make your work more accessible and will give your company more (and better) users.
Screencasts und Live-Streams
Screencasts sind zwar sehr aufwändig in der Produktion. Sie sind jedoch gerade bei weniger erfahrenen Entwicklern ein beliebtes Medium, um den Einstieg in eine Software zu meistern. Sceencasts können außerdem über verschiedene Plattformen gehostet werden und zusätzliche Reichweite genieren. Auch bei der Medien-Arbeit können Screencasts zusätzliche Anreize für die Berichterstattung sorgen. Youtube, Tutorial-Webseiten oder Course-Plattformen sind beispielsweise Addressaten.
Eine Alternative zu Screencasts sind Live-Streams, bei denen Nutzer mit eingebunden werden. Diese Form des Engagements nutzt beispielsweise die Software Courier. Die Abrufzahlen der Videos zeigen allerdings, dass bei Bewegtbild-Formaten immer eine Kosten-Nutzen-Abwägung stattfinden sollte. Es gibt jedoch auch Beispiele für kleine Software-Projekte, die fünf- und sechsstellige Abrufzahlen verzeichnen.