As long as I’m ranting about computer books (and their feeble imitators: online tutorials), let me unleash on my next favorite annoyance: Stupid, stupid examples.
\n
\nThe DOS 5 manual gave plenty of examples of how to work with subdirectories. (That’s what they called folders before they were called folders.)<\/p>\n
The example read like this, though I’m quoting from memory here:<\/p>\n
Say you want to create a subdirectory called
GRAPES<\/code>.<\/p><\/blockquote>\nI. Kid. You. Not.<\/p>\n
Grapes<\/em>.<\/p>\n
The demo in the manual went on to create various fruit subdirectories. That was it. Utterly useless because they never explained why you would need to create a subdirectory called
GRAPES<\/code>.<\/p>\nI got to meet the gal who wrote that DOS 5 manual. I was invited to the Microsoft campus to help them with some PR, and the gal who wrote the manual was at the table \u2014 along with the guy who wrote the
DOSKEY<\/code> utility.<\/p>\nThe
DOSKEY<\/code> utility guy I got to thank profusely. But to the DOS 5 manual lady I said \u2014 as best as I can recall \u2014 “Grapes<\/em>? Creating a subdirectory called grapes<\/em>?”<\/p>\nShe brushed it off as a generic, non-offensive example, but it remained utterly unrealistic.<\/p>\n
Still, unrealistic examples exist through documentation and training materials.<\/p>\n
Sometimes the examples are simply trite, such as the “Let’s create a Circle class” example in any object-oriented programming book. But more annoying to me is when the author uses the same example throughout the entire book.<\/p>\n
For example, the MySQL manual I’m using. It really illustrates how to setup and manipulate a database for your music collection. It’s a good example, and it works well with the material. My issue: It’s the same example he uses throughout the book.<\/p>\n
Now I understand: It’s a pain to have to recreate a new example to demonstrate each new concept for MySQL. Even so, all databases are not the same. I may not actually type in an entire database, so it’s not that creating a different example is too much work. It’s just that I’d at least least prefer other, real-world examples.<\/p>\n
In my books, I try using different examples for each situation. In my programming books, I have databases for the seven dwarfs, the Wizard of Oz<\/em>, a checking account, a stock-tracking account, and other examples that mix names, numbers, and different types of data. Beyond making the text interesting, the idea is to show other ways information can be stored and manipulated. You just can’t get that if you’re using the same old database over and over.<\/p>\n
And, most definitely, in my books on file organization, I use real world examples. Definitely not
GRAPES<\/code>.<\/p>\n","protected":false},"excerpt":{"rendered":"As long as I’m ranting about computer books (and their feeble imitators: online tutorials), let me unleash on my next favorite annoyance: Stupid, stupid examples.<\/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-2886","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\/2886","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=2886"}],"version-history":[{"count":5,"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/2886\/revisions"}],"predecessor-version":[{"id":2891,"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/2886\/revisions\/2891"}],"wp:attachment":[{"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2886"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=2886"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.wambooli.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=2886"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}