I love learning how to do new things on the computer. It’s a constant reminder to me how many computer books, as well as Internet documentation, really suck.
In fact, let me make this point perfectly clear: Computer documentation sucks about 93 percent of the time.
The main reason it sucks is that the person who’s writing the documentation knows the product too well. They’re intimate with the inner workings and subtleties. So they forget what it’s like to just start out. They lack the ability to stand back and look at what they’re doing from a completely blank slate without any references.
There are other reasons for the suck factor as well.
For example, the person writing the documentation online may just be copying notes from the developer or programmer. So not only do they not know how the product works, they don’t care because they’ll never use it themselves.
They may be working with a beta or earlier version of the project. That’s because it takes longer to work on the documentation than it does the product. I don’t view this as an intentional issue, though it’s neglectful when they don’t update their documentation after the project’s release.
Finally, the person doing the documentation may be the programmer himself, in which case they’re not only overly familiar with the material they just plain don’t want to do the job.
The most famous example of that last point was a tidbit of text I saw in one manual. It referred to a command line switch on a communications program like this:
-K The function of this option should be obvious.
I’m serious. That’s what the documentation said.
The key to teaching something new is to get into the head of someone who is doing something for the first time. You have to step back and look at things fresh. You have to think about what a beginner wants to do, and what’s important to them.
It’s also necessary to figure out what not to write about. As someone intimate with a product, you may find some feature really cool and be eager to document it. A beginner doesn’t feel the same way, no matter how compelling that feature may be. In fact, they may never love the feature, and until the person writing the documentation understands that, the documentation will always suck.
I’m fond of saying that I’ve never really written anything new in my computer books. All I’ve done is tried to teach myself using existing material, found that material lacking, and then written my own stuff that’s much better. My recent experience has shown that there’s still a need for such documentation, so I suppose my job isn’t quite done yet.
This article is so close to my key frustrations with programming computers, that I feel compelled to have a mini-rant. A similar problem is caused by programmers who feel comments are for lesser mortals.
I read (in the Unix-Haters Handbook) about this priceless gem in the source code of Unix:
/* You are not expected to understand this */
Clearly, it would take too much effort to actually make the code readable (i.e. obvious), or write meaningful comments, so why bother.
Far too often I have been required to dig through someone’s code when I join a project, and read through cryptic stuff that a ‘star’ programmers wrote to show off their abilities. Since I work in engineering (and all developers are engineers), pesky things like code review and documentation are conveniently ignored. A special level of hell is reserved for programmers who feel that a program should die (or switch jobs) with them.
Comment by sriksrid — May 11, 2011 @ 8:47 pm
There’s an arrogance to not documenting their code, but also a survival instinct. They feel that they’re so good they’re irreplaceable, which means that they’re arrogant. So they poison-pill the code to make it near impossible for anyone else to maintain it.
Of course, there’s also the opposite end of the spectrum:
a = b; // place the value of b into aComment by admin — May 11, 2011 @ 10:34 pm
Another problem with some computer books is that they are just so, for lack of a better word, dry. Reading them is like being lectured in a classroom. Your books have a more conversational tone. When I bought MS-DOS version 5 (actually the Compaq version), it came with a very thorough technical reference. It even had a whole chapter on batch files. Despite reading it carefully, I could not seem to understand FOR-IN-DO loops. Later I got my
hands on “Advanced MS-DOS Batch File Programming” and discovered that FOR-IN-DO loops are quite easy to use. Once I became comfortable with FOR-IN-DO, I went back to the Compaq DOS manual to see what had been missing. It turns out that all of the information was there, but it was presented in a dry, technical, matter-of-fact way that failed to demonstrate how very useful the commands could be.
Comment by sean bernard — May 14, 2011 @ 7:40 pm
I’m having the same issue learning Java right now. Can someone write an example of how to create a class without using the “Circle” class? My guess is that Sun originally demonstrated with that example, because everyone since then has aped it. Not working.
Glad you liked the Advanced Batch book. Like you, I was bored with the useless examples of batch file programming. So I wrote a better book.
Comment by admin — May 14, 2011 @ 7:45 pm