🔥 Tech Blips #22.7
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)
There's a great blog post by Gernot Starke about the principles and requirements for technical documentation.
The blog post contains a very nice overview of the requirements for technical documentation.
Many of these aspects (such as version control, continuous updating, appropriate tools, etc.) implicitly or explicitly propagate the technique of "Documentation as Code":
- Req-02 Current
- Req-07 Maintainable
- Req-09 Version-controlled
- Req-11 Continuously updated
- Req-10 Appropriate tools
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
Convert the content to a publication format like HTML, DocBook, PDF, etc.
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 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 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.
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.