Dieser Leitfaden befindet sich aktuell in der Erstellung durch das Autorenteam und wurde bisher noch keinem Review unterzogen. Daher ist dieser Leitfaden zum aktuellen Zeitpunkt noch nicht vollständig. Es können daher fehlerhafte, lückenhafte oder unvollständige Informationen enthalten sein.

Allgemeine Dokumentations-Tipps

1. Übersicht

Übersicht

Nachfolgender Abschnitt liefert ihnen leicht anwendbare und nützlichen Tipps, wie sie einen effektiven Umgang mit Dokumentationsaufgaben erreichen können. Die Tipps beschränken sich nicht nur auf die Technische Dokumentation, sondern lassen sich universell auf Dokumentationsaufgaben anwenden.

Goldene Dokumentationsregeln

1. Dokumentation muss einfach zu verstehen sein

• Schreiben sie in aktiver Form und verwenden sie kurze Sätze.
• Nutzen sie leicht verständliche und einfache Sprache.
• Schreiben sie oberflächlich und überfrachten sie den Leser nicht mit zu vielen Details.
• Gehen sie auf Details nur dann ein, wenn sie der Zielgruppe einen Mehrwert bieten.
• Visualisieren sie Informationen durch den Einsatz von Tabellen und Grafiken.

2. Dokumentation muss einfach zu nutzen sein

• Schreiben sie zielgruppenorientiert und setzen sie die domänenspezifische Fachsprache ein.
• Verwenden sie einen lösungsorientierten Schreibstil, die den Leser bei seiner Aufgabenbewältigung unterstützen.
• Nutzen sie moderne Dokumentationsmittel wie Hyperlinks zur semantischen Kontextnavigation oder wiederverwendbare Textcontainer.
• Stellen sie eine einfache Auffindbarkeit und leichte Zugänglichkeit zu der Dokumentation für die Zielgruppe sicher.
• Achten sie bei der Verwendung von Informationen und Bildmaterial auf die Vermeidung von Datenschutz- oder Compliance-Verstöße.
• Verwenden Sie Dokumentationsvorlagen und stellen sie Referenzdokumentationen zur Verfügung.
• Löschen Sie leere Kapitel und Vorlage-Texte, die aus einem Template-Dokument stammen (Diese sind nach der nächsten Aktualisierung der Vorlage veraltet, Sie brauchen sie also nicht mehr!)

3. Dokumentation muss spezifisch und nachvollziehbar sein

• Trennen sie die Dokumentation je nach Zielgruppe und Nutzen in unterschiedliche Dokumentationsartefakte, wie z.B. Administrationshandbuch, Anforderungsdokumente, Technische Dokumentation, etc. auf.
• Nutzen sie ein Versionsverwaltungssystem für die Dokumentationsartefakte um über die Versionshistorie vorgenommene Dokumentationsänderungen einfach nachzuvollziehen.

4. Dokumentation muss einen sinnvollen Wertebeitrag liefern

• Der Dokumentationsnutzen muss größer sein als die Kosten das Dokument zu erstellen und aktuell zu halten.
• Binden Sie die Autoren und die Leser, für die die Dokumentation geschrieben wird, in den Definitionsprozess der Dokumentationsrichtlinien mit ein.