« MacMacs | Main | Update to the Update »

The time has come, the Walrus said, to speak of many things. With apologies to Lewis Carroll, that is most certainly true, and today, the time has come to speak of documentation. This is, of course a subject that is now near and dear to my heart, thanks to my current task of documenting the work of not one, but two projects, one of which is at least four years old. If this sounds like the first circle of hell, you're wrong. It's actually the seventh. I can also say that I now understand why Tina the Tech Writer,is so brittle. Because I could easily commit mayhem seven or eight times a day in this epic task.

Now, I've done programming before. Did it for more than a few years as a full - time job, and I still do AppleScript as a need arises, either for my own needs, or for various friends and folks I know well enough to do work for on the cheap. I know it's a pain in the keister to comment and write notes on stuff, and that doing documentation gets you about as much respect as eating a ham sandwich in a synagogue. But documentation is important, in some cases as important as the code. How many times have you stopped using, or never started using an application because you couldn't figure out how to do something? Yes, the UI should help you, but there needs to be clear, well-written documentation that explains program functionality, and even shows you how to do stuff. This isn't just a Mac/Windows thing, or just a GUI thing. The better Unix man pages have examples of the command they are the manual for.

Documentation is also hard to do correctly. I was required to attend a week - long class in creating documentation in the Air Force, and it was some of the most mentally draining work I've ever done. The hardest part was removing the phrase, They'll know what I mean from my vocabulary. Because when you are writing documentation, you aren't writing it for the people who know the application intimately. You're writing for the people that don't. You're writing for the people who may have never seen your application before. You may even be writing for people for whom this is the first time they've ever used a personal computer before. (Before you laugh too hard at this, there are more people like this than you think.)

So now, you have to define terms. All of them. You sometimes have to define the definitions. If you provide step - by - step instructions, you have to test them. But you have to test them as thought the only information you have are those instructions. It's tedious, stupefying, mind - numbingly draining work. But it's the only way to create documentation that works. You also learn to simultaneously love and hate products like Snapz Pro.

Don't get me wrong, I think Snapz is without a doubt the best screen capture/screen recording application on any platform. But I also cringe when I have to fire it up, because it means that I'm again writing documentation, and that means that I'm going to be in hell again. (Actually, I find most of Ambrosia's products elicit that love / hate reaction. I love what they do, but there are times when I wish they didn't write such damnably addictive digi - crack.) But the tedium of the process is only half the problem. It may even be only a tenth of the problem.

The really painful part is getting the source documents for your documentation. If you've never experienced this, then trust me, the phrase, Just pull it down from CVS is another way of saying I haven't documented a damned thing unless a gun was at my head, so you can just decipher code comments and my notes written in a code that would make Von Neumann become a janitor. Even worse is when they tell you, Oh, I've got a bunch of documentation somewhere, I've been keeping it over the years, I'll just upload it to you.

At that point, I really recommend drinking. Heavily. Straight vodka works for me, just make sure it's really cold. Because programmers really suck at documentation. Now to be fair, it's not their sweet spot. It requires a totally different way of thinking about things, and having been on both sides, the context switch can be quite painful. But when you're trying to save money, what are you going to spend money on, good documentation, or good programmers?

Okay, so the people who send you money will complain, but that's what third party books are for, right? So the documentation is relegated to the coffee stain in front of the totem pole, the coders aren't given time to even comment stuff for themselves. Then you come upon the release date, and some poor bastard is given two months to create coherent docs from random notes that even a room with 10,000 monkeys would look at in disgust. Of course, the documentation will suck, but do the people who created the problem, i.e. project managers who blew off documentation from the start catch the hell? Oh no, it's the tech writers, for not doing their jobs. Because this isn't the fault of the programmers either. They may create crap for documentation, but they are creating that crap for their own use, and for that purpose, the crap works well.

It's the project managers, and the project managers' bosses, and so forth who don't get that the only intelligent way to do documentation is to have the documentation people involved before the first beta. When you release a beta, you better have some beta documentation for it. Yes, it means more expense, and maybe slows things down, but you get a couple of benefits from it.

First, you get better documentation, because instead of trying to do everything at once, you get documentation built over time. No 100+ - hour weeks, but rather a steady, manageable process that follows the development process. The documentation can be beta tested, and if you're smart, you release it in a comment - able form, (PDF is excellent here), so that you get tester comments on what works and what doesn't.

Second, you get a better end application, because you get a completely different set of eyes on the thing. If you can't explain how to use an application in simple, non - tortuous prose, then you should be questioning the design of the application, or at very least the UI. Because if explaining how to use it is torture, then using it won't be far behind. We've all seen applications that make you wonder exactly what was going through the developer's head when they designed that feature. My personal favorite is Eudora's infamous x-eudora-blah codes.

What an idea. Instead of designing a proper settings UI, we'll just hide a boatload of functionality in secret codes, and then not ship the definitions of those codes with the application, so you have to know the secret web address, or that Adam Engst, of TidBITS has a special list set up to email you the definitions. Even better, we'll include a code that says, literally, DO NOT TOUCH (x-eudora-setting:14701 for those who care). Nothing that says why you shouldn't touch this setting, and evidently it didn't occur to anyone to just disable it and not mention it. There's a bunch of them that say nothing more than DO NOT LOCALIZE. Let me just say that defining the setting is not the same as properly documenting it.

But, this is a perfect example of what happens when documentation isn't taken seriously. I don't expect that this essay will magically right all the wrongs with documentation. I'd be surprised if it even gets taken seriously. Because the ROI on documentation isn't obvious. You can't count the people who don't get frustrated by your application, who are able to use good documentation to be productive, and really become fans of the product, and recommend it to their friends and co-workers.

But there is one thing that can be done. If you use an application, and the documentation is really good, then let the company that created it know. Call them up, email them, whatever, and tell them that the documentation really helped you use that program, and that because of it, you'll be using it more, and recommending it more. Along with that, perhaps an email to that program's competitors pointing out that, in part, good documentation is why you are using a competitor's products. Maybe positive, or positive/negative reinforcement will help, because we've all been complaining for years, and straight negative reinforcement certainly isn't making a difference.

Comments