I love code documentation. Here are some reasons:

1. It reduces cognitive load when maintaining legacy code (helps you figure out which button to press faster). Docs communicate how the code should be working at a specific point in time, and this can reduce debugging time when tracking down a bug.

2. It communicates intent. This helps future developers to respect the wisdom in legacy code (“Why, oh, why did they build it this way?!?”). This can prevent them from introducing new bugs because they think they can do it better.

3. It increases the speed with which new developers can add business value. This allows you to scale your dev team faster.

4. It decreases the communication necessary to understand someone else’s code. This means less interruptions for the person who originally wrote it.

5. It better supports asynchronous development. This means that remote dev’s, team members is other timezones, or folks who like to sleep in and work nights and weekends are not handicapped by not being able to speak with the original author.

6. It decreases the clustering of knowledge in the minds of one or two invaluable team members. These are the guys that “If we lost them, it would be a very bad day.” Docs protect the business from disaster by departure.

So yeah, I think docs are awesome.

But first, why do so few developers write docs?

1. There is a undercurrent of bravado in the development community that dismisses documentation. “You should just be able to read the code and understand what it does.”

2. Docs don’t write themselves. You have to make a conscious effort to write them, you have to choose a documentation framework, and refer to it occasionally. As developers, our natural tendency is to be happy with our code as soon as we get it working. But caring dev’s will groom their code after they get it working – refactoring it and adding documentation to explain what it does.

3. Docs add zero functional value, and thus, they are never pressing. Code gets written because it gets prioritized. Users complaining about an annoying bug, or product owners asking for a new feature – these things tend to be prioritized over things like “make our codebase easier to understand.”

4. Docs have to be maintained, just like code. If you don’t maintain the docs, they can mislead you and cause you to create bugs.

5. Docs cannot be tested.

6. Many brilliant dev’s cannot spell and have trouble communicating. I have saved this for last, perhaps because it is the most important. There is a very human side to programming, and it should not be dismissed. Some of the most talented engineers I have ever known have been dyslexic, had trouble spelling, or found communication with humans more difficult than communication with computers. I empathize with them, and I can imagine that spelling mistakes make them feel unintelligent or ashamed. So, they naturally stick to what they are good at – writing code, and they avoid what they are not – explaining things in human terms.

Now that we’ve discussed why many developers do not write documentation, I’d like to share a few principles that I have when it comes to docs. I prefer documentation that is beautiful in the code over docs that are beautiful in a doc generator. Secondly, I prefer documentation that is structured, rather than unstructured, to enforce developers to follow a standard of documenting methods, rather than cowboy commenting.

TomDoc is probably the best documentation method for Ruby. It is beautiful, human readable without being overly verbose, structured, easy to learn, and it can generate nice docs.

When it comes to JavaScript, things are a little less clear cut.

JSdoc and YUIdoc are structured, but they are complicated and hard to learn. They give you pretty generated docs, but result in ugly code. If your team has any resistance to documenting things, this will be exacerbated by a steep learning curve and the resulting ugly code.

Docco is the other extreme. There is nothing to learn, but this results in zero standardization, and developers who do not explain things by nature will be no better off than they were before if they use Docco.

Dox is structured, it is uglier in the code than TomDoc, and it generates documentation. But you cannot search the docs, which is a big lose. If you want to search for stuff, you have to search the codebase, and now you’re back to reading code, not docs. And since the code is uglier than TomDoc, you might as well be using TomDoc.

For these reasons, I prefer to forgo a documentation generator and use TomDoc in both JS and Ruby. This creates a single, easy-to-learn documentation standard across the codebase. Maybe one day someone will make a TomDoc generator for JS like they already have for CoffeeScript.