Coding Your Documentation By Hubert Klein Ikkink

To write (technical) documentation usually means we leave our coding environment and for example need to start a word processor or open a wiki where we type our documentation. Documentation-as-code allows us to apply the same development techniques we use for our source code to our documentation. We make sure the documentation is close to our code, make it part of our builds and even write tests for our documentation. We will look at Asciidoctor as a tool which transforms documents written with Asciidoc, a Markdown-like markup, to HTML, Docbook and PDF. When we use the very simple Asciidoc markup we only focus on the content and structure of our documentation. And the really nice feature of Asciidoctor is that we can include the contents of external files, partially or completely, in the generated output. This means our documentation can reference source files that we know are correct, because we have written tests for those source files. Also because the markup is simply text we can simply see differences between versions using the tools we as developers are already familiar with. Asciidoctor has an extension API which allows us to add new functionality to Asciidoctor. This way we can also include diagrams described with text and generate graphical images from them. We can use Java as well to write extensions and we will see how we can write our own extensions. HUBERT KLEIN IKKINK Hubert Klein Ikkink is also known as mrhaki. He uses his alias to write on his blog “Messages from mrhaki” (https://blog.mrhaki.com/). On this blog he writes short tips and tricks about Groovy, Grails, Gradle, Spock, Spring and Asciidoctor. Today he works with Java and Groovy during his daytime job at JDriven in the Netherlands. He also wrote books on Gradle, published at Packt Publishing and spoke at different conferences and meetups.