Trivial Pursuit – API MarkDown (2)

Fasst drei Jahre nach dem ersten Beitrag zum eigenen API MarktDown ergibt sich ein zweiter Beitrag zum Thema. Bei der Durchsicht der eigenen Projekte fiel auf, dass in dem Projekt rest-markdown-plugin noch immer FreeMarker als Template-Engine verwendet wurde. Die erste Ad-Hoc Umstellung der Template-Engine auf FreshMarker scheiterte jedoch kläglich.

Erweiterungen für Asciidoctor erstellen

Wer technische Dokumentationen erstellen muss, hat mit Asciidoctor eine einfache aber leistungsfähige Lösung zur Hand. Asciidoctor ist ein Textprozessor, der Vorlagen aus einfachen Textdateien in HTML, PDF, EPUB3 oder Docbook Format umwandelt. Durch die Asciidoctor API können dazu noch eigene Erweiterungen integriert werden.

Entwickler Dokumentation ohne Textverarbeitung

Leider hält sich in vielen Bereichen immer noch hartnäckig das Gerücht, das für eine ordentliche Dokumentation eine Textverarbeitung notwendig ist.
Üblicher und übler Vertreter dieser Gattung ist Microsoft Word. Die Nachteile durch dieses Programm für Software Entwickler sind nahezu endlos. Programmfehler, komplizierte Bedienung, Ablenkung von Inhalt durch WYSIWYG, Inkompatibilitäten zu anderen Programmen oder eigenen älteren Versionen, automatisierte Dokumentationstools unterstützen das Format nicht.

Source Code Dokumentation

Streit entbrennt in der Regel darüber, was der Entwickler der Software an weiterer Dokumentation in seinem Code benötigt.

Das Zitat von Cory House “Code is like humor. When you have to explain it, it’s bad.” bringt auf humorvolle Weise ein grundlegendes These auf den Punkt. Schlechter Code wird durch Dokumentation nicht besser.