- People who read help are stupid. People who write help are smart. Don't ever forget that, and don't ever let your readers forget it.
- Complexity of grammatical construction correlates in a positive manner with the perception of intelligence; thus it is advisable under all circumstances to endeavor to utilize sentence structures and locutions commensurate with the level of one's own education.
- It is considered presumptuous to address readers as if they were present. Passive voice is preferred.
- When documenting software that allows you to create, change, or delete something - your contact information, for example - write a separate topic for each task. It's far too confusing to provide instructions for more than one task in a single topic, or to write steps that involve choices (such as "If you need to add a new telephone number, click Add Number. If you need to change a number, edit it in the text box"). Remember, your readers are stupid.
- Take every opportunity to continue selling your product. Remind users how attractive it is, how sleek its design and stylish its colors. Remind them how intuitive and easy it is to use.
- People open the help when they are scared of making a mistake. When presenting a task, point out how easy it is. When you get to the step where people tend to go wrong, tell them it's really simple. People like to be reassured that they are smart enough to get it right. Remember, they're stupid.
- Don't bother with teh spelling checker. It's for careless people who either can't type very well or are too ingorant to spell well. Your smarter than that.
Sunday, July 18, 2010
Seven Habits of Highly Defective Technical Writers
If you want to be a Highly Defective Technical Writer, you need to learn industry worst practices. Here are seven to get you started.
Labels:
grammar,
humor,
parody,
product documentation,
quality,
satire,
skills,
technical writing,
writing sins
Subscribe to:
Post Comments (Atom)
I would add to remember that most people have never used a user interface before and will have no idea that a check box must be selected and that the Save button saves their changes (whereas the Cancel button cancels their changes). This brings your list up to eight, you can add one more before incurring the curse of Miller and Horn.
ReplyDeleteYES on everything, but particularly number 5.
ReplyDeleteWhen I edit technical content, words such as "easy," "simply," or "just do xxxx" have very short life spans.
I am not about to court the Curse of Horn. There may be Another Seven Habits coming up, though. :-)
ReplyDeleteAs you've no doubt discerned, I'm reacting to worst practices that I've observed in the wild. There are far more than seven.