Rocco: Ablauf dokumentiert

Docco ist ein kleiner Dokumentationsgenerator, der im Sinne des literarischen Programmierens

• die enthaltene Texte als HTML-Dokumentation aufbereitet,
• den Code über Syntax-Kolorierung leichter lesbar macht.

Das eine oder andere tun andere Werkzeuge auch, der Unterschied ist, dass Docco beides macht, und die Ergebnisse noch in einer Seite gegenüberstellt. So, dass man Texte und dazu gehörende Code-Abschnitte schön nebeneinander lesen kann. Das benötigt natürlich Breite, aber die ist ja nun vorhanden.

Dass diese Gegenüberstellung eine gute Idee war, beweisen die Portierungen von Docco, das für CoffeeScript/Javascript  gedacht war. Die Abbildung  wurde übrigens mit der Ruby-Portierung Rocco erstellt.

Springen zwischen Kapiteln

Im Augenblick ist diese Art der Präsentation auf einzelne Dateien fokussiert. Zusammenhänge für größere Anwendungen werden nur über Menüs hergestellt, mit deren Hilfe man zwischen den einzelnen Dateien hin- und herspringen kann.  Verglichen mit einem Buch, wären wir hier auf der Ebene der Kapitel. Da fehlt also noch etwas.

Mehr Rocco

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.