Thoughts on agile software development
As a developer, I work with the IntelliJ IDEA development environment, as do many other developers. I don’t want to discuss its many advantages for developers here, but rather how to use Playfair with the AsciiDoc plugin.
While searching for a name for the new project, I looked up the inventor of charts for fun. I was amazed to find that this person actually existed. William Playfair (born September 22, 1759, near Dundee, Scotland; † February 11, 1823 in Covent Garden, London, England) is a pioneer of information graphics and is considered the inventor of bar and pie charts. What an unexpected opportunity to honor this man. The name also fits perfectly with an open source project that aims to provide simple charts without a lot of fuss. This article shows what has changed since the first bar chart and how much Java takes off our hands.
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.
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.
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.
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.
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.
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.
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.
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.