Anne Gentle
by Anne Gentle

Looking for a way to invigorate your documentation team and grow that team to include developers, designers, and writers of all backgrounds? Plus, how about inviting some robots into the mix for good measure? Let’s treat docs like code.

Treating docs like code is:

  • Collaborating with contributors efficiently by keeping docs close to code or in the same system as code, with a source file concept and an output for deliverables.
  • Building documentation as repeatably and consistently as possible across multiple platforms. While typically done with open source tools, the main driver is not open source but open, repeatable, consistent collaboration.
  • Applying software development tools and techniques to documentation about software, application programming interfaces (APIs), or other technical topics.
  • Learning enough about web development to be dangerous and create beautiful, modern docs.
  • Valuing technical accuracy and consistency.
  • Trusting team members to value documentation, respect end-users needs, and advocate for the best deliverables for consumers of the documentation.
  • Automating and integrating documentation builds so you and your teams can focus on content.

Choose your docs-as-code adventure

In a choose your own adventure series, you first pick the look for the site, then discover the developer language that pairs with the static site generator and then the CICD integration follows. We walk through setting up the development environment, and then show how to automate using docs CICD pipelines including Read the Docs, GitHub Pages, and Netlify.

You may also test the docs by with Continuous Integration (CI) systems like TravisCI or CircleCI. If you need to work within existing CI systems, choose a tool that other teams use within your organization, and your choice of output is not limited by the CI system. In other words, the test frameworks in TravisCI or CircleCI do not dictate your deployment system.

Here are three example documentation sites you can write and build using an SSG with CICD.

Choose your adventure and start one of these sites - and learn ways to treat docs like code along the journey.

Ready to learn more?