Eine gute Dokumentation ist genau, vollständig, verständlich und wartbar. Es vermittelt effektiv die notwendigen Informationen an seine beabsichtigten Publikum (n) und hilft ihnen, ihre Ziele zu erreichen. Hier ist eine Aufschlüsselung der Schlüsselqualitäten:
Genauigkeit:
* sachliche Korrektheit: Die dargestellten Informationen müssen wahr und aktuell sein. Veraltete oder falsche Informationen sind schlechter als keine Dokumentation.
* Konsistenz: Die Dokumentation sollte durchweg konsistente Terminologie, Stil und Formatierung verwenden.
Vollständigkeit:
* deckt alle relevanten Aspekte ab: Enthält alle erforderlichen Informationen für das beabsichtigte Publikum, um das dokumentierte Thema zu verstehen und zu verwenden. Dies kann Einrichtung, Nutzung, Fehlerbehebung, Einschränkungen und verwandte Konzepte umfassen.
* ausreichend Detail: Bietet genügend Details, um hilfreich zu sein, um unnötige Kürze oder überwältigende Ausführlichkeit zu vermeiden. Das Detailniveau sollte für die Zielgruppe geeignet sein.
Verständlichkeit:
* Klarheit und Selbstverständlichkeit: Verwendet eine klare und einfache Sprache, vermeidet Jargon oder technische Begriffe, es sei denn, dies ist absolut erforderlich (und dann zu definieren).
* logische Organisation: Die Informationen werden logisch und leicht zu befolgen, häufig mit Überschriften, Unterüberschriften und visuellen Hilfsmitteln.
* gut strukturiert: Einfach zu navigieren und spezifische Informationen schnell zu finden (z. B. durch Indizes, Inhaltstabellen, Suchfunktionalität).
* Angemessenheit für das Publikum: Geschrieben auf einem Verständnis, das für die Zielgruppe geeignet ist (Anfänger, Intermediate, Experte).
Wartbarkeit:
* Einfach zu aktualisieren: Die Dokumentation sollte leicht zu aktualisieren und auf dem neuesten Stand zu halten, während sich das dokumentierte Thema weiterentwickelt. Die Verwendung eines Versionskontrollsystems wird dringend empfohlen.
* Modular und wiederverwendbar: Komponenten der Dokumentation können in verschiedenen Kontexten wiederverwendet werden.
* verwendet ein überschaubares Format: Die Auswahl des richtigen Formats (z. B. Markdown, umstrukturiertesText, ein Wiki) ist wichtig, um die Bearbeitung und Renderung zu erleichtern.
Andere wichtige Aspekte:
* Barrierefreiheit: Die Dokumentation sollte für Menschen mit Behinderungen zugänglich sein und nach den Richtlinien der Zugänglichkeit.
* Beispiele und Abbildungen: Mit Beispielen können Diagramme, Screenshots und andere visuelle Hilfsmittel das Verständnis erheblich verbessern.
* Suchfunktionalität: Wenn die Dokumentation groß ist, ist die Bereitstellung einer robusten Suchfunktion von entscheidender Bedeutung.
* Versioning: Klar die Version des dokumentierten Betreffs angeben.
Kurz gesagt, eine gute Dokumentation antizipiert die Bedürfnisse seiner Benutzer und hilft ihnen dabei, ihre Aufgaben zu erfüllen. Es handelt sich um eine Investition, die sich bei reduzierten Supportkosten, erhöhten Benutzerzufriedenheit und einer schnelleren Einführung des dokumentierten Produkts oder Systems auszahlt.
