The secret to successful autogenerated docs merkt etwas an, was eigentlich selbstverständlich sein sollte, aber doch gern übersehen – oder gar verdrängt? – wird:
The word “autogenerated documentation” is a misnomer: there is no automatic generation of documentation. Rather, the autodocumentor should be treated as a valuable documentation building tool that lets you get the benefits of cohesive code and comments, as well as formatting, interlinking and more.
Keine ernst zu nehmende, neue Programmiersprache kommt heute ohne einen Dokumentationsgenerator aus, der üblicherweise HTML-Seiten erzeugt. Der Generator bringt so ein Stück Agilität in die Entwicklung, der Code und seine Dokumentation – als formatierte Kommentare im Code – sollen so immer gleich aktuell sein.
Der Generator nimmt dem Entwickler somit die Formatierung ab, letzterer muss eigentlich nur dafür sorgen, dass die enthaltenen Texte mit dem Code etwas zu tun haben und richtig ausgezeichnet sind. Diese Art der Dokumentation enthebt einen also nicht des Schreibens. Das Problem ist nur, dass viele Entwickler sich auf eine kleine Untermenge dessen beschränken, was so ein Generator zu bieten hat.
Jedenfalls ist – meiner Beobachtung nach – die Dokumentation von Open-Source-Projekten meist besser, ausführlicher als die von Projekten im eigenen Hause. Da keimt der Verdacht auf, dass die Beobachtung etwas mit der Zielgruppe zu tun hat, an die sich die Dokumentation wendet. Niemand schreibt gern für die Schublade, und niemand hat auf der anderen Seite viel Lust, nur unwesentlich veränderte Textbausteine zu lesen. Ein Henne-Ei-Problem. Ohne aktive Leser, Nutzer und entsprechende Würdigung der Schreibanstrengungen wird sich das wohl nicht lösen lassen.