Dokumentieren

Damit euer Software-Paket sinnvoll genutzt werden kann, sind Dokumentationen erforderlich, die Beschreiben, wie eure Software installiert, betrieben, genutzt und verbessert werden kann:

• Diejenigen, die euer Paket nutzen wollen, benötigen Informationen,

  • welche Probleme eure Software löst und was die Hauptfunktionen und Einschränkungen der Software sind (→ README)

  • wie das Software beispielhaft verwendet werden kann

  • welche Veränderungen in aktuelleren Software-Versionen gekommen sind (→ CHANGELOG)

• Diejenigen, die die Software betreiben wollen, benötigen eine Installationsanleitung für eure Software und die erforderlichen Abhängigkeiten

• Diejenigen, die die Software verbessern wollen, benötigen Informationen

  • wie sie mit Fehlerbehebungen zur Verbesserung des Produkts beitragen können (→ CONTRIBUTING)

  • wie sie Sicherheitslücken melden können (→ SECURITY)

  • wie sie mit anderen kommunizieren (→ CODE_OF_CONDUCT) können

Alle gemeinsam benötigen Informationen, wie das Produkt lizenziert ist (LICENSE-Datei oder LICENSES-Ordner, → LICENSE) und wie sie bei Bedarf Hilfe erhalten können.

Tipp

cusy Seminare:

• Software-Dokumentation mit Sphinx

• Technisches Schreiben

Siehe auch

• Eric Holscher: Why You Shouldn’t Use “Markdown” for Documentation

• Tom Johnson: 10 reasons for moving away from DITA

• Tom Johnson: Jekyll versus DITA

• Google developer documentation style guide

• Google Technical Writing Courses for Engineers

• Cusy Design System: Schreiben