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.
![What is Documentation as Code? And why do you need it?](/content/images/size/w1200/2022/10/Screenshot-at-Oct-16-10-25-22.png)
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.
![](https://www.workingsoftware.dev/content/images/2022/10/image-10.png)
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
![](https://www.workingsoftware.dev/content/images/2022/10/image-14.png)
Convert the content to a publication format like HTML, DocBook, PDF, etc.
![](https://www.workingsoftware.dev/content/images/2022/10/image-16.png)
![](https://www.workingsoftware.dev/content/images/2022/10/image-17.png)
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 ()