Docs As Code

Have the whole team deliver current, useful, documentation using the minimum of effort.
Contributed by

Alec Clews

Published July 22, 2021
Collection
1

What Is Docs As Code?

Docs As Code (also known as “Docs Like Code”) is a popular approach to delivering documentation for software projects.

There are three common themes that you can expect to see.

  1. Adopt an “agile” approach to content creation
  2. The whole team is responsible for content, not just the technical writers
  3. A culture of adaptation and improvement to both content, and processes, over time.

Docs As Code image copyright Anne Gentle. Released under an MIT license.

Why Do Docs As Code?

  • Deliver valuable documentation faster with higher quality, because there are multiple voices working collaboratively
  • Avoid documentation being a bottleneck in the release cycle
  • Release technical writers to deliver higher value content (information architecture, customer experience, ....)
  • Remove need for proprietary technical writing and publication tools.

How to do Docs As Code?

Use developer tools, and process, to create and deliver content. Specifically:

  1. Text based file content with embedded, lightweight, markup tags. Examples include Markdown, reStructuredText, AsciiDoc

  2. Developer based workflows. For example:

    1. Version Control using tools, such as Git
    2. Change control driven though bugs and feature requests tickets
    3. Content reviews and merges
  3. Machine generated content. For example:

    1. Create diagrams from text using tools like Mermaid.js or PlantUML
    2. Add machine generated text by running CLI programs when a document is published (e.g. to insert current software version identifiers or other content)
    3. Use text processing tools to extract and use text from other files (e.g. fragments of released source code)
  4. Automated testing and verification. For example use:

    1. Vale to validate your written text against machine readable style guides
    2. Spectral or Redocly to validate your Open API Specifition files
  5. Continuous delivery, using static site generators (for example Sphinx or Hugo). Note: This process is optional

Look at Docs As Code

Links we love

Check out these great links which can help you dive a little deeper into running the Docs As Code practice with your team, customers or stakeholders.


Except where noted, content on this site is licensed under a Creative Commons Attribution 4.0 International license. This site is graciously hosted by Netlify