Diese Webseite nutzt nur technisch notwendige Cookies.

So macht Dokumentation Spaß! Lesenswerte Doku schreiben

Das Nervigste am Entwickler-Job ist die Doku!

Ich beweise Dir das Gegenteil und erkläre, wie Du brauchbare Doku schaffst.

Starten wir!

Warum brauchen wir Dokumentation?

Trockener Schmöker = Doku?
Trockener Schmöker = Doku?

Dokumentation ist keine Pflicht Aufgabe, sondern die Möglichkeit, die Nutzer-, Entwickler- und Kunden-Zufriedenheit zu steigern. Bei Doku denken wir an dicke Papierhandbücher, welche bei jedem Produkt mitgeliefert werden.

Zwischen rechtlichen Texten sollten sich Anwendungshinweise finden. Soll das gute Doku sein?

Nein. Doku soll helfen, die Software richtig zu bedienen, den Sinn von Funktionen zu verstehen, effizienter zu arbeiten, Personen auszubilden, vergessene Fakten nachzuschlagen oder Informationen auszutauschen.

Wieso ist die meiste Dokumentation so schlecht?

Ja schön, Du hast immer noch Dokus. Hier sind die Top-Gründe warum:

  • Zu viel, zu wenig, nicht existent: Der Umfang der Doku ist schwer zu wählen. Standardmäßig ist keine Doku dabei oder 600 Seiten lang.
  • Doku über offensichtliche Dinge: Technische Schreiber und Entwickler dokumentieren häufig nur das Offensichtliche. Oben rechts ist ein Button zum Verarbeiten. Keiner erklärt aber den Prozess des Verarbeitens und warum er schiefgehen kann.
  • Alt: Die Software macht große Sprünge, während die Doku nur stiefmütterlich behandelt wird. Alte Dokus und Screenshots sind ein No-Go.
  • Laber und Nur-Pflicht-Form: Viele Entwickler haben 0 Bock auf Doku und schreiben deshalb nur, um die Seiten zu füllen und den Chef ruhig zustellen. Weder Chef, Kunden noch sonst wer liest das.
Das will keiner lesen
Das will keiner lesen
  • Vorwissen: Doku ist oft unverständlich, da der Entwickler viel Geheim- und Vorwissen nicht dokumentiert. Für ihn ist alles klar und einleuchtend. Für andere ist es eine unbrauchbare Anleitung.
  • Adressat überfordert: Ein Entwickler braucht eine andere Doku als ein Anwender. Ein Anwender interessiert sich nicht für das, was neue Kunden wissen wollen. Doku braucht einen Adressaten und viele Formen.

10 Top-Tipps für bessere Dokumentation

1. Sehe Doku als Chance – nicht als Last

Doku ist häufig die lästigste Aufgabe Nummer 1, wenn man Entwickler befragt. Trotzdem ermutige ich Dich, Deine Meinung zu überdenken. Deine Doku feiert die erfolgreiche Vollendung eines Features oder eines Releases. Die Doku zeigt, dass ihr nicht nur programmieren könnt, sondern auch die Software anderen einfach beibringen könnt. Ihr könnt auf ein Feature zurückblicken und nochmal rekapitulieren, was ihr getan habt.

Ich halte Doku selbst als eine gute Abwechselung zum Programmieren. Während man beim Programmieren oft stundenlang auf der gleichen Stelle herumtappt (Bug), kannst Du beim Doku schreiben einfach Wort an Wort hängen. Du hast ein Endprodukt, welche mit jeder weiteren Minute wächst und sich verbessert.

2. Meilensteine und Wortzahl

Halte Dich motiviert mit Meilensteine. Halte Dir sichtbar vor – 8 von 20 Feature habe ich bereits dokumentiert. Ich habe 1000 Worte bereits verfasst. Jeden Tag schreibe ich vor der Entwicklung 200 Worte zu einem Feature. Vermeide Hauruckaktionen und dokumentiere jeden Tag ein bisschen.

3. Ein Satz Doku besser als gar keiner

1 Satz ist oft hilfreicher als 600 Seiten Handbuch. Der Entwickler / Doku-Schreiber sollte lieber weniger machen, als die Super-Doku vor sich als Aufgabe herzuschieben.

Keiner gewinnt einen Preis, wenn Du eine lange Doku hast.

In dem ersten Satz kannst Du die Motivation hinter der Software vorstellen oder dem Entwickler auf die Entwicklungsumgebung aufmerksam machen.

Oft brauchen wir nur einen leichteren Start. Sage Dir, dass Du 10 Minuten Doku schreibst und dann aufhörst. In der Regel ist der Start der Schwierigste und Du vergisst schnell, dass Du nur 10 Minuten schreiben wolltest. An Tagen, wo nix geht, kannst Du nach 10 Minuten aufhören und weiter programmieren.

4. Wer liest diese Doku – Welche Fachsprache brauchen wir

Häufig ist der Adressat unbekannt. Doku muss maßgeschneidert für den Adressaten sein. Der Nutzer muss nichts über API Routen wissen und der Neu-Kunde braucht kein Tutorial. Es gibt nicht die 1 Dokumentation, sondern wir brauchen viele kurze, angepasste Dokus.

  • Neu-Kunden: Preise, Top 10 Features, Vergleiche zwischen Softwaretypen
  • Bestandskunden: Tutorials zu Features, Prozesse
  • Admins: Wie installiere ich die Software? Wie verwalte ich Nutzer?
  • CEO: Preise, Strategie, Problemlösung
  • Entwickler: API-Doku, Kommentare im Code, Coding-Umgebung.
Entwickler Doku ist wichtig
Entwickler Doku ist wichtig

5. Formatierung ist King

Gute Dokus sind strukturiert mit Überschrift und Unterüberschriften und beinhalten Tabellen und Schaubildern. Nutzer sollen Themen einfach mit dem Inhaltsverzeichnis und dem Glossar finden und dabei keine Kaugummi-Texte lesen.

6. Einfache Lösungen sind die Besten

Wir können 30 Tage uns damit beschäftigen, was die beste Doku-Software ist. Trotzdem ist die einfachste Formatierungsart – Markup oder MS Word / LibreOffice meist die beste Option. Die Technologie ist für alle verfügbar, schnell und unkompliziert.

Wir wollen die Barriere so gering wie möglich machen, um den ersten Satz der Doku zu schreiben. Kooperation kann über SharePoint oder Git stattfinden – Hauptsache ihr vermeidet das Senden von Version 1.1.1-Update-Neu-Doku.md via Mail.

7. Keine Angst vor Bildern, Screenshots und Diagrammen

Bilder sagen mehr als 1000 Worte.

Nehme immer die beste Art der Informationsvermittlung. Wenn Deine Doku aus 1000 Screenshots besteht, ist das ok. Ein „schnelles“ Video mit einer Bildschirmaufzeichnung ist besser als jeder Text, den Du schreiben kannst. Alle Audio und Video-Dateien sollten kurz und nach Mini-Themen untergliedert sein, anstatt ein Mega-Blockbuster von 240 Minuten aufzuzeichnen.

8. Erinnerungen setzen – Aktuell zu halten

Halte die Doku aktuell! Überprüfe regelmäßig mit einem Termin in Deinem Kalender, wann Du die Doku anpassen musst. Jeder Release ist ein guter Zeitpunkt, um die Doku zu checken.

Splunk macht es richtig
Splunk macht es richtig

Die Doku kannst Du mit dem gleichen Takt, wie die Software versionieren. Selbst wenn sich nichts geändert hat, kannst Du mit der neuen Version bestätigen, dass diese noch relevant ist.

9. Keiner hat was davon, wenn Du komplexe Sprache verwendest

Beim wissenschaftlichen Schreiben meinen viele Forscher sie müssten sich so komplex ausdrücken wie möglich, um mit ihrer Intelligenz anzugeben. Die Kunst liegt aber darin Sachverhalte einfach und knapp zu erklären, während Fachbegriffe sofort erklärt werden.

Doku soll informieren und nicht mit Fachsprache verschrecken.

Einfache Sprache besteht aus kurzen und mittellangen Sätzen mit aktiven Verben. Wir stellen Sachverhalte neutral dar und schweifen nicht vom Thema ab. Jeden Satz, den wir sparen können, löschen wir.

10. Jedes neues Feature, ein neuer Abschnitt in der Doku

Selbst wenn für Dich als Entwickler alles eine Selbstverständlichkeit ist, solltest Du alle Features in der Doku nennen. Nicht jeder kennt die Tastenabkürzungen, welche in der neuen Software funktionieren. Außerdem bleiben sonst „versteckte“ Features dem Nutzer verborgen. Die Feature-Entwicklungszeit gilt dann als verschwendete Zeit, weil das Feature keiner verwendet.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

get rss abo

Jetzt
Abbonnieren
academy

Erhalte Free
Security Kurs

Jeden Monat teile ich mit Mitgliedern
4 neue praxisnahe Tutorials (je 1000+ Wörter).


Trage Deine Mail, damit Du
Deine Coding + Hacking Skills erweitern kannst!