Y U No Write Documentation? (part 1)

Note: This is the first part of an ongoing ‘writing good documentation’ series.

Let’s face it, good documentation is hard to find. If you’ve been programming for more than a few days, you’ve probably been frustrated by trying to read the instructionals on how to use X application/framework/library/whatever. I can’t begin to tell you how many times I’ve tried some new majigger only to find that its documentation was lacking.

And we might as well go ahead and acknowledge that writing documentation isn’t exactly thrilling. That said, how many times have you written some code, then had to look at it six months later for some reason and thought, “the hell does this do?” Happened to me the other day, and I had to trace through my own code again to figure it out. The thing about documentation is that it’s going to make *everybody’s* job easier, so why not take the extra hour or two to hammer out some decent docs?

But, They Might REPLACE ME!!

Might as well get the obvious out of the way. If you’re putting all your special knowledge down on paper, of course your boss is going to want to get rid of you! After all, there’s no need to keep you around any more, right? Maybe that’s a relatively reasonable assumption on the surface. But if you’re writing docs that make your code easier for everyone to use, it really makes you more valuable to your employer. Ultimately, they’re worried about the bottom line. So if you’re saving your bosses some dough by making things easier for everyone to use, it gives them that much more reason to keep you around. Besides, there will inevitably be some case where the docs just don’t bestow expertise. That’s when you go to the documentation *writer*. They clearly know what they’re doing (or at least they *presumably* know what they’re doing).

Think of it like a vehicle’s manual. You can search the web or your owner’s manual to find out how to do some of the simpler things. But if something is seriously wrong with it, you don’t do it yourself: you take it to the mechanic. They’re vastly more familiar with a vehicle’s moving parts than you could be in your few hours of Google searches. The same goes for documentation. You can write some of the best documentation around, but you’re not going to remove the need for the original developer.

The thing that doesn’t make sense is that if “programmers are lazy,” why do we still hate to write documentation? It’s easy to think of it as taking on more work. But writing documentation is really about reducing your workload by decentralizing the knowledge of how something works. You’re putting solid documentation in a place where everyone can access it and better understand the program. This way, you’re distributing the knowledge over a larger sample of people. A better way to look at it is as creating a script for humans. Think about it: it makes a task easily repeatable (by others), and breaks the task into simpler problems/tasks that are easy to do individually. When you think about it that way, how can you *not* want to write documentation?

Making It Incremental

One thing that one of my coworkers does that i like is he takes notes as he’s developing. This way, not only is he solidifying the logic in his brain, he’s also creating a skeleton for more official docs. Once you have a set of barebones notes, actual documentation becomes a whole lot easier. Plus, when you can explain something thoroughly, you know you’ve really got it. Not to mention the fact that it really makes things easier when you face similar problem on some other server/project. Your notes get rid of that “What did we do the last time this problem came up? I can’t remember” problem. Instead of wasting the brain power on remembering the solution to some obscure problem, you’re spending the brain power on ctrl-f’ing your notes for the right keywords. That’s a pretty good trade-off, I’d say.

That covers some of the advantages of writing good documentation. In the next installment of the series, I’ll start talking about how to actually create good documentation.