.toString();

As development team we decided to write our documentation with Asciidoc. As other parts in our landscape use gradle as the build tool, thus we opted for the asciidoctor-gradle-plugin to generate the documentation. The documents have embedded plantuml diagrams describing the architecture, but to our surprise the toolchain did not render them correctly. Apparently the diagrams use features of plantuml that are not supported in the version provided by default by the toolchain.

We found out we had to update to later versions of asciidoctorj-diagram and plantuml. The version of asciidoctor-gradle-plugin (3.3.2) is now about a year old (from February 2021) and probably its dependencies also. Unfortunately it’s rather hard to find which versions are used by the asciidoctor-gradle plugin and how to update to newer versions.

Documenting spring restcontrollers with spring-restdocs is a sure way to get great documentation. It allows one to document API endpoints based on examples used in a test, and document specific fields in a response. It’s even possible to document additional attributes of a field in a JSON response.

My coworker points me to the presentation of Aslak Hellesøy, Sub-second acceptance tests. As we’re struggling with long running and brittle acceptance tests, that provoking title triggers my interest, and I start watching the recording…​

I really like maven for the structured way it provides for defining and building a project. But sometimes I wish for a less verbose notation than the XML of the Project Object Model (POM). For example, gradles dependency notation is far shorter than mavens dependency declaration.

The Thoughtworks Technology Radar is well known for showing technology trends and choices. For my project I wanted to have the same thing, not use the hosted public version from Thoughtworks, but a selfhosted option. Therefore I choose to base it on the Zalando opensource tech radar, and create a way to use a CSV file as input so updating would be an easy thing to do.