Wie gelingt ausgezeichnete Softwaredokumentation?
Nichts ist in der Softwareentwicklung nachhaltiger als eine saubere Dokumentation – schließlich habt Ihr ja auch stets von gut dokumentierten Bibliotheken profitiert.
Zum Glück gibt es heute effizientere Umgebungen als Word oder Confluence dafür. Mit einer vereinfachten Auszeichnungssprache (Habt Ihr das Wortspiel im Titel erkannt?) lassen sich Dokumente in einer IDE oder jedem beliebigen Texteditor erstellen und bearbeiten. Dabei bleiben alle Inhalte und Konfigurationen einfach lesbar und editierbar, ganz im Gegensatz zu eigenwilligen WYSIWYG-Programme oder Wiki-Plattformen. Wenn die Dokumentation als «Code» zur Verfügung steht, dann kann sie auch wie normaler Quellcode mit allen modernen DevOps-Werkzeugen verarbeitet werden.
Ausgezeichnete Softwaredokumentation gelingt durch einen ganzheitlichen Ansatz aus
- einer vereinfachten Auszeichnungssprache,
- einem Dokumentationsgenerator und
- einfach umsetzbaren (wahrscheinlich überraschenden) organisatorischen Maßnahmen
Und das ist genau das, was Ihr in diesem Talk hören und sehen werdet.
Vergesst alle Vorurteile und schlechte Erfahrungen, die Ihr über Softwaredokumentation kennt. Ab heute könnt Ihr es besser machen!