Table of Contents
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 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 ;-)
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
Plain text markup language for writing technical content
AsciiDoc IDE Plugins
Convert: Documents to the publication formats like HTML, DocBook, PDF, etc.
Processing AsciiDoc into a document model and converting it to specified target output