What authoring tool works best for developer documentation, especially when documenting APIs? I’ve used a number of authoring tools (Flare, Robohelp, Confluence, Word, Drupal, Google Docs, and others), and while different tools fit different scenarios with varying strengths, if you’re writing developer docs, nothing works quite so well as static site generators coupled with a docs-as-code publishing workflow.
Docs-as-code tools means to embrace tools that treat docs just like developers treat software code. To treat docs like code generally means doing some of the following:
In short, treating docs like code means to use the same systems, processes, and workflows with docs as you do with programming code.
Just because you can manage docs like code, should you? What exactly are the advantages of treating docs like code? Here are a few reasons to embrace docs-as-code tools for documentation.
If you work with developer documentation, chances are you’ll be working on a wide variety of deeply technical topics and will be reliant on engineers to contribute and review the docs. By implementing a docs-as-code approach, you’ll enable developers to more easily contribute and participate in the documentation.
Most developers are comfortable with Markdown, enjoy being able to work in their existing IDE to edit content, understand how to collaborate in a git repo using branching, merging, and code review tools, and are generally comfortable with the whole code-based process and environment. By using tooling that is familiar to them, you empower them to contribute and participate more fully with the documentation.
When you can build from the server by simply pushing content into a Git repository, it greatly simplifies the act of publishing. You can make edits across a number of docs, commit your code into your doc repo, and when you merge your branch into a gamma or production environment, a server process automatically starts building and deploying the content to your server.
At first, learning the right Git commands might take some time. But after working this way for a few weeks, these commands become second-nature and almost built into your typing memory. Eliminating the hassle of publishing docs allows you to focus more on content, and you can push out updates quickly and easily. Publishing and deploying the output is no longer a step you have to devote time towards.
When your tech writing team collaborates in the same Git repository on content, you’ll find a much greater awareness around what your teammates are doing. Before committing your updates into the repo, you run a
git pull to get any updates from the remote repository. You see the files your team mates are working on, the changes they’ve made, and you can also more easily work on each other’s content. By working out of the same repository, you aren’t siloed in separate projects that exist in different spaces.
Docs-as-code tools give you incredible flexibility to adapt or adjust to your particular environment or company’s infrastructure. For example, suppose the localized version of your website requires you to output the content with a particular URL pattern, or you want to deliver the content with a certain layout in different environments, or you want to include custom metadata to process your files in a particular way with your company’s authentication or whitelisting mechanisms. With docs-as-code tools, the files are open and can be coded to incorporate the logic you want.
To read details about switching to docs as code tools, see Case study: Switching tools to docs-as-code.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson