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.
\n
\nIn fact, let me make this point perfectly clear: Computer documentation sucks about 93 percent of the time.<\/p>\n
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.<\/p>\n
There are other reasons for the suck factor as well.<\/p>\n
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.<\/p>\n
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.<\/p>\n
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.<\/p>\n
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:<\/p>\n
I’m serious. That’s what the documentation said.<\/p>\n 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.<\/p>\n It’s also necessary to figure out what not<\/em> 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.<\/p>\n 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.<\/p>\n","protected":false},"excerpt":{"rendered":" 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.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[],"class_list":["post-2876","post","type-post","status-publish","format-standard","hentry","category-main"],"_links":{"self":[{"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/2876","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=2876"}],"version-history":[{"count":2,"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/2876\/revisions"}],"predecessor-version":[{"id":2878,"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/2876\/revisions\/2878"}],"wp:attachment":[{"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2876"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=2876"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=2876"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}-K<\/strong> The function of this option should be obvious.<\/code><\/p>\n