Smarte Dokumentation: AsciiDoc
Welcher Entwickler schreibt schon gerne Dokumentation? ;-) Aber für ein gutes Design und vor allem wenn die Software auch von anderen Leuten benutzt werden soll kommt man nicht drum herum. Seit ich Debian-Pakete baue habe ich manpages im nroff-Stil geha(c)kt. Sogar die zsh-lovers liegen in der Quelle als nroff vor. Und es war nicht wirklich angenehm zsh-Syntax in nroff zu tippen. Da die Dokumentation für grml auch von Release zu Release zunimmt, wollte ich da jetzt ein brauchbares System. Das System soll einfach, halbwegs performant, stabil, (auch bei Debian) gewartet und natürlich dokumentiert sein. Selbstverständlich sollen auch verschiedene Dateiformate für den Output möglich sein. Fein wäre es halt auch, wenn andere Leute die an der Dokumentation mitschreiben diese möglichst einfach nutzen können. Vor vielen Monaten schon einmal reingeschaut, jetzt geht es auch bei mir in den Produktiveinsatz: AsciiDoc.
AsciiDoc is a text document format for writing short documents, articles, books and UNIX man pages. AsciiDoc files can be translated to HTML and DocBook markups using the asciidoc(1) command.
AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.
Der Output schaut einfach fein aus, der Weg dorthin ist angenehm. Beispiele gibt es direkt auf der Homepage des Projektes. Bisher habe ich alles was ich gebraucht habe sehr schnell und auch intuitiv bekommen. Wer also mal in die Verlegenheit kommen sollte, Dokumentation schreiben zu müssen: ein Blick in Richtung AsciiDoc kann sich lohnen.