An Introduction to Docs-as-Code

by Sean Marquez (& contributors)

When documentation is good

Docs are up-to-date
Docs are easy to navigate
Docs are easy to maintain

When documentation is bad

Docs are not up-to-date
Docs are hard to navigate
Docs are hard to maintain

What is a Docs as Code approach?

Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code.

Advantages to a Docs as Code approach

Writers integrate better with development teams
Developers will often write a first draft of documentation
You can block merging of new features if they don’t include documentation, which incentivizes developers to write about features while they are fresh

To adopt a Docs as Code approach, consider the following…

Language
Toolchain
Methodology

Language

Markup language used to write the docs

e.g., Markdown, ReStructuredText, Asciidoc, LaTex

Template language, a superset of a markup language, used to format the docs
```
e.g., Liquid, Jinja2, Handlebars
```
Source language of the toolchain used to render the docs
```
e.g., Ruby for Asciidoctor, Python for Sphinx
```

Toolchain

Issue Tracker
```
e.g., Jira, GitHub, GitLab
```
Conversion Engine / Static Site Generator
```
e.g., Sphinx, Asciidoctor, Hugo
```
Distributed version control system
```
e.g., git
```

CI/CD service & publishing platform

e.g., TravisCI, GitHub Actions | GitHub Pages, ReadTheDocs, Netlify

Some publishing platforms have CI/CD services built-in

Methodology

Docs-Driven-Development

Write your docs first, then implement what you documented

Agile Development Practice
```
e.g., scrum, kanban
```

Code (Docs) Reviews

Have someone review your docs (e.g., as a pull request on GitHub)

Example Projects that use a Docs-as-Code Approach

NodeJS
```
https://github.com/nodejs/nodejs.org
```

SoCal Linux Expo A/V Team

https://github.com/socallinuxexpo/scale-av-web/

This presentation!

https://github.com/capsulecorplab/docs-as-code

References

Closing thoughts…

With a sufficient number of users of an API, it does not matter what you promise in the contract; All observable behaviors of your system will be depended on by somebody. - Hyrum’s Law

https://xkcd.com/1172/