---
title: "Limits to the idea of treating docs as code"
date: 2017-06-02
description: "First, what we mean by docs like code When docs aren’t like code  Release frequency Release complexity <a href="
canonical_url: https://idratherbewriting.com/2017/06/02/when-docs-are-not-like-code/
---
# Limits to the idea of treating docs as code
- Working in plain text files (rather than binary file formats like FrameMaker or Word)

 - Collaborating using version control such as git and GitHub (rather than collaborating through large content management systems or SharePoint-like check-in/check-out sites)

 - Automating the site build process (rather than manually publish and transfer files from one place to another)

 - Running validation checks using custom scripts to check for broken links, improper terms/styles, formatting errors, etc. (rather than spot checking it manually)

 - Storing docs in the same repositories as the programming code itself (rather than keeping it separate in another space)

 - Versioning docs through git tags/releases (rather than duplicating all the files to archive each release)

 - Using an open-source static site generator like Sphinx, Jekyll, or Hugo to build the files locally, using your customized theme with all files open and editable in an IDE-like editor such as Atom (rather than relying commercial tools with proprietary, closed systems that function like black-boxes)

In short, treating docs like code means to use the same systems, processes, and workflows with docs as you do with programming code.

![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/limitstodocsascode.png)

Few people do all of the above points. For example, it doesn’t make sense for me to store my docs in the same repos as code, because most of the code repos are never deployed publically, and even if they were, engineers release much less frequently than tech docs. This brings me to my main point: docs aren’t just like code, and we should probably not push this docs-as-code treatment too far.

## When docs aren’t like code

Here are a few ways that docs aren’t like code:

 - [Release frequency](#releasefrequency)

 - [Release complexity](#releasecomplexity)

 - [Review processes](#reviewprocesses)

 - [Company support](#companysupport)

### Release frequency

Engineers like to release updates a lot less frequently than tech writers. For example, one open source project I work on has *quarterly* releases. They do this for good reason. They don’t want to keep updating the code so frequently that they exhaust the patience of the third-party developers. A lot of changes to code aren’t always backwards compatible, and if engineers published an update to code every two weeks, the Trump-like pace may be seen as out of control and haphazard.

In contrast to code, docs should be released much more frequently. If you see a typo, fix it and push out a new version of the documentation. As pull requests come in identifying broken links, or you need to add a little note here and there based on current usage, you should do so freely and regularly — much more regularly than with code releases.