🔥 Tech Blips #22.7

In this technology newsletter: Documentation as Code, AsciiDoc and Asciidoctor.

🔥 Tech Blips #22.7
Write technical documentation in Visual Studio Code
Tech Blips is a technology newsletter for CTOs, tech leads, software architects and software engineers - in short, for all technology enthusiasts!

Every month I try to summarise some techniques, tools, languages and frameworks or platforms on the cloud and web horizon that are worth taking a look at.

TL;DR in this technology newsletter:

  • Techniques: Documentation as Code (Trial)
  • Tools: Asciidoctor (Adopt)
  • Language and Frameworks: Asciidoc (Adopt)

Documentation as Code

Techniques / Trial

Documentation as Code

There's a great blog post by Gernot Starke about the principles and requirements for technical documentation.

Principles of technical documentation
This article collects fundamental requirements for technicaldocumentation, especially software architecture documentation, togetherwith ideas how to *satisfy* those.

The blog post contains a very nice overview of the requirements for technical documentation.

Requirements of technical documentation (Source)

Many of these aspects (such as version control, continuous updating, appropriate tools, etc.) implicitly or explicitly propagate the technique of  "Documentation as Code":

What does "Documentation as Code" mean?

"Documentation as Code" means that your documentation process benefits from the same techniques used in software development.

Some of these techniques are:

  • Storing content in a version control system such as Git
  • Separation of content (e.g. AsciiDoc), configuration (e.g. Asciidoctor) and presentation (e.g. HTML, PDF, ePUB, ...)
  • Use automation for compilation, validation, verification, and publishing (e.g. in your CI/CD pipeline)
  • Use development collaboration tools to review documentation such as code (e.g., pull requests)
  • ...and use your IDE to write technical content ;-)

Example

Author the content

Write, validate and preview your documentation content in Visual Studio Code with the AsciiDoc extension

Convert the content to a publication format like HTML, DocBook, PDF, etc.

Generate the documentation with asciidoctorj
Documentation as HTML Output
Documentation as PDF Output

AsciiDoc

Languages & Frameworks / Adopt

Asciidoc Website

AsciiDoc is a plain text markup language for writing technical content. It’s packed with semantic elements and equipped with features to modularize and reuse content.

Try out Asciidoc with zero dependencies online: https://asciidoclive.com/edit/scratch/1

AsciiDoc content can be composed using a text editor, managed in a version control system, and published to multiple output formats.

AsciiDoc Content (left), Preview (center) and its calculated structur (right)

AsciiDoc is designed to strike a balance between systematic, machine-oriented syntax and natural language. This design affords AsciiDoc the ability to capture and encode nearly all the semantics of a highly-structured language while still being readable in source form.

Asciidoctor

Tools / Adopt

Asciidoctor Website

Asciidoctor is an open source text processor that parses AsciiDoc into a document model and converts it into output formats such as HTML, DocBook, PDF, EPUB and other formats.

With Asciidoctor you can integrate the processor into your CI/ CD pipeline and publish the documentation according to the stakeholders.

Include Documentation as Code in your build and deployment pipeline

Although Asciidoctor is written in Ruby, that doesn't mean you need Ruby to use it. Asciidoctor can be run on a JVM with AsciidoctorJ or in any JavaScript environment (including the browser) with Asciidoctor.js.