Ein weiteres Leid...
Zu Anfang begann ich Spezifikationen/Systementwürfe in Word95/97 zu schreiben, die viele Entwickler nicht kümmerten und keiner las. Heute sind wir im Jahre 2011 und ich schreibe immer noch technische Dokumentation in Word 2003/2010. Diese Art der Niederschrift technisch, fachlicher Inhalte hat meist ein Problem, dass sie mit sinkendem Abstraktionsgrad sehr stark der eigentlichen Umsetzung hinterherhinkt.
In openwms.org begann ich zu Anfang meine Doku mit OpenOffice Document Format zu schreiben, was sicherlich Word gleichberechtigt ist, allerdings war das eigentliche Problem damit nicht gelöst, da diese Doku immer noch zu weit weg vom eigentlichen Code.
Daher hab ich mir angesehen wie die Spring/JBoss Community ihre Doku schreibt und war davon direkt überzeugt.
Die Dokumentation von openwms.org wird ausschliesslich in DocBook Format geschrieben, passend zum aktuellem Release der Software und generiert durch die Zuhilfenahme von Apache Maven. Als nettes Feature wird sie natürlich in den gewohnten Formaten HTML/HTML-SINGLE und PDF generiert und ist stets für jede Release Version verfügbar.
Das Ganze mit Maven und DocBook zu bauen war etwas tricky, aber machbar :-)
Wer sich also hinsichtlich technischer Dokumentation frei bewegen kann sollte sich einmal DocBook (aktuell in Version 5) und den super Editor XMLMind ansehen. Und wer dann noch mehr wissen möchte wie man mit Maven das alles zu "Papier" bringt sollte nicht zögern und mich anschreiben...
Keine Kommentare:
Kommentar veröffentlichen