Treating documentation like code: a practical account


Are you interested in developing docs like code? Are you frustrated by the lack of available information as to what that really means and how exactly you're supposed to do it? Welcome to the club!

"Treating documentation like code" is somewhat of a buzzword bingo term these days. You can find any number of blog posts, presentations, and articles online expounding on the theory and merits of the idea. When I was presented with an opportunity to truly integrate documentation into the agile development process almost 2 years ago, I couldn't find any information that could teach me how to treat docs like code. Since then, I've worked with a team of passionate software engineers to bring a long list of 'awesome-future' ideas for treating documentation like code into practice. In this presentation, I'll lay out how we create, test, build, and publish our documentation using agile methodologies, so others starting down the same road have a path to follow.

In the beginning, we had a great idea - documentation should be developed, tested, and built just like the products we make. The keystone of this grand vision was the idea that docs live in the same repositories as the code, use the same development tools and code review processes, and follow a continuous delivery model. I'll go over the tools we chose to write, build, and test the docs; the responsibilities of the software engineers and technical writer, respectively, for creating and maintaining content; the docs information architecture we developed; how we incorporated syntax and grammar checks into code testing; and how we build and deploy our documentation automatically.

  • Conference: Write the Docs NA
  • Year: 2017

About the speaker

Jodie Putrino