January 1, 2013

Tech Pubs Tuesday: Code Proximity

So I’m going to try a new thing in 2013 — a weekly series of short posts on the craft of software technical writing. Welcome to Tech Pubs Tuesday! Today’s topic is code proximity: what it is and why you want it.

There are lots of paths to broken documentation, but one of the most popular paths is to make sure your documentation source and software source live as far apart from each other as possible. In practice, this could mean:

• keeping your documentation source in a separate repo from your software source
• keeping your documentation in a proprietary binary format that only a few people can actually open and use
• keeping your documentation authors as far as possible from your software authors

By contrast, in a healthy project:

• documentation source sits right alongside your software in a /doc directory, embedded inside your source code as doc comments, or both
  • corollary: documentation source should be in an open, plain text format
• documentation builds as part of your normal CI process or build process
• documentation authors work right alongside software authors (or are the same people)

In other words, documentation must be part of your project, just like your tests and build scripts. It needs to be in your face every time you view your repo. The last thing you want is for it to be hidden away, in a place you don’t know about, in a format you don’t understand, controlled by people you don’t really know. Code proximity is your first line of defense against documentation rot.

Comments are closed at this time. Thank you for your participation.