Warning: This post is mostly a rant.
I read a lot of technical documentation. Software manuals, mostly. Some programming books. 99% of all these books, posts, and guides are utterly worthless. And half of each document or book in the remaining 1% is fluff that I could do without. Because most of these books "cover" very technical topics, it is hard to describe just how nonsensical most of the writing is, in terms a layperson can understand. So, I decided to write an example based on something everyone is familiar with. What follows is a description of a common household object as it would be described by most software manuals today, with the name changed to confuse the innocent. Grammatical errors are intentional. Let me know if you can figure out what the hell I am talking about.
The Flizba Model Paradigm
- A flizba is a very important device around the building. A flizba has a handle and can be used to swat flies. A flizba can also be used to remove dirt.
- A flizba is longer than a typical breadbox but the total volume is less than that of the space inside a breadbox.
- Flizbas can be made by hand or can be made in factory. Preferably one that does not have a witch flying around in it.
- Important Note: You should not use a flizba to swat at a witch which may be flying around in a factory.
- When making a flizba by hand, be sure to wrap the wire very tightly.
- To get to the flizba, turn the doorknob to the left (unless the door is not a door, in which case use the appropriate method, as desired).
The contents of this post is Copyright © 2013 by Grant Sheridan Robertson.