What is Documentation as Code? And why do you need it?
"Documentation as Code" means that your documentation process benefits from the same techniques used in software development.
Table of Contents
There's a great blog post by Gernot Starke about the principles and requirements for technical documentation.
Gernot StarkeThe 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 is "Documentation as Code"?
"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)
- ...and use your IDE to write technical content ;-)
Example
Author the content
Convert the content to a publication format like HTML, DocBook, PDF, etc.
Example Documentation as Code Toolchain
The following list shows you an example toolchain to introduce the Documentation as Code technique.
Author: Write, validate and preview your documentation content
AsciiDoc
Plain text markup language for writing technical content
AsciiDoc IDE Plugins
Convert: Documents to the publication formats like HTML, DocBook, PDF, etc.
Asciidoctor
Processing AsciiDoc into a document model and converting it to specified target output
Publish: Build and Deploy documentation artifacts
- AsciiDoctor Maven / Gradle Plugins
- DocToolChain
- Antora
Comments ()