FreshMarkers Roman Numbers
FreshMarker is quite a small library, about 475 KB in size. Therefore there is always room to make a few small additions. One of these is the display of numbers and loop variables with Roman numerals.
AsciiDoc
Generating AsciiDoc from OpenAPI.yml
Sometimes changes to a library are made so easily that it’s not really worth talking about. The Maven Plugin from posts Build Automatisierung mit eigenen Mojos verbessern and Trivial Pursuit – API MarkDown generates AsciiDoc documentation for simple OpenAPI descriptions. So far, the Maven Plugin uses a JSON description as input format. Since the YAML representation is used more frequently, its support would also be desirable.
Presentations with AsciiDoctor
Sometimes even developers want to present something. It’s nice when there’s a tool that picks up the developers in their comfort zone. Software developers are a special clientele and have very specific requirements for a software solution for creating and giving presentations.
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.
Trivial Pursuit – API MarkDown
Die Dokumentation einer REST API sieht immer sehr schick aus. Ob es sich um eine interaktive Swagger Seite handelt oder um eine statische Darstellung eines anderen Tools, alle Endpoints, Parameter und Datentypen sind akkurat aufgelistet.
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.
API Dokumentation mit spring-boot-docs
Documentation is a love letter that you write to your future self. Damian Conway Es gibt die verschiedensten Arten die eigene Rest API zu dokumentieren, Tools wie Swagger können da helfen oder man schreibt selbst Markdown oder Asciidoc Dokumente. Wenn die Swagger Beschreibung nicht zur Generierung der API genutzt wird, dann kann man nie sicher … Read more