Docs as Code

author:Eric Holscher

Docs as Code refers to a philosophy that you should be writing documentation with the same tools you use to write code. This means following the same workflows and integrating into development teams. It enables a culture where writers and developers both feel ownership of documentation, and work together to make it as good as possible.

Generally a docs as Code approach gives you the following benefits:

  • 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

There is a lot more to building a proper Docs as Code workflow. There are a couple books we recommend that you check out:

  • Docs Like Code - Anne Gentle
  • Modern Technical Writing - Andrew Etter

Docs as Code at Write the Docs

Write the Docs has had a number of talks that touch on this topic over the years.

2015 North America

  • Riona MacNamara talked about how adopting Docs as Code has completely transformed how Google does documentation.

2016 North America

  • We had a panel with folks from Rackspace, Microsoft, Balsamiq, and Twitter, all talking about how they are adopting these practices.

2016 Europe

The Docs as Code concepts are widely practiced in the software industry, and are gaining adoption in the writing community.