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

  4. Automated testing and verification

  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.

Discuss with the Community


Open Practice Library Logo
Open Practice Library

powered by

Open Innovation Labs Logo
Connect with our Community:
Except where noted, content on this site is licensed under a Creative Commons Attribution 4.0 International license.