Wednesday, July 17, 2013

What is good documentation?

Imagine this - you are assigned to a new project. An admin gives you permissions on the repository and you grab a copy of the code (via git, svn, or whatever). As you look in the directory, you see a mismash of files and directories. You recognize some of them (lib/, src/, test/, and so on), but some of them are weird (server/, conf/ vs. config/ vs. cnf/). And, sure enough, the project lead is on vacation this week and the other developer is in meetings all morning. Slashdot, here we come, right?

This sorry situation appears to be the norm in most development teams I've worked with. Most information about how to set up an environment, how to function within the team, and what expectations are tends to be transmitted by word of mouth. What little that is written down is always out of date or just blatantly wrong.

Everyone deplores the state of affairs, but very few do anything about it. It seems like a Sisyphean task, constantly pushing that boulder uphill without any support from anyone else. Management certainly doesn't agree that documentation is as important as shipping code. Developers are notorious for not wanting to write anything except code. Testers are supposedly clueless (more on this in another post). And, worst of all, ops thinks everyone else is an idiot out to make their life harder than it already is. No-one trusts anyone, so no-one is going to take the risk of actually writing something down.

Most application teams (dev, ops, analysts - everyone!) operate like guilds from the Middle Ages. Not with a deliberate intent to hide knowledge for the purposes of maintaining a monopoly to collect rents (though the effect ends up being the same). Instead, there's no provision made to actually manage the generation, storage, and transmission of information. Instead, the lowly apprentice has to petition the journeymen and masters of the team to provide them with whatever scraps of information they can get. This becomes the root cause for two unfortunately common phenomena:
  1. Many companies expect a new employee to take up to 3 months to become useful.
    • And consume a "useful resource" at the same time.
  2. Senior developers are never allowed move off a project.
Good documentation fixes both of these problems. 

So, what does good documentation even look like? The short answer is "good documentation is sufficient unto itself." The ideal is that most answers to most questions is not only within the documentation, but can be found by the average reader. It is clear, concise, complete, and comprehensible. It has enough information for the new reader, yet can be read as a reference by the old hand. And it is both current and versioned. Whenever a change happens in the code, it is reflected in the documentation.

Before you say "Impossible!", look at your favorite opensource products. The really good ones - you know which ones I'm talking about. These are the tools, frameworks, and modules that you can understand exactly what it will (and won't!) do within 15 minutes of easy reading. They have examples. Tutorials. References. The number of FAQs is very small.

Most importantly, the number of times you have to google for something or ask in an IRC channel or mailing list? Zero. Zilch. None.

Good documentation is also not always written. The very best form of documentation is executable. This guarantees that the documentation will always be current. It has to be, otherwise the project doesn't work. It's also documentation that everyone likes - it's code and it saves everyone time. Executable documentation includes:

  • Tests (unit-tests, integration tests, customer tests, etc)
    • Cucumber is ideal as executable documentation.
  • Deployment and environment management
  • Build tools (make, Ant, Maven, Grunt, Vagrant)

I'm going to be writing posts for each of these in the future.