Leon Bambrick was probably in a really good mood, because he read my previous rant about how hard it is to write technical help docs and decided he would write a short guide in the comments to that post. It turned out to be a master piece of simplicity and elegance. Thanks leon. :) Here's what he wrote:
Technical Writing: breadth first with iteration.
writing, whether technical or creative, always has defects. it never has the elegance of code, it can never be evaluated completely. there are always more ways you can look at it.
so accept that it's going to be bland and imperfect and boring. accept that very few people are going to read it or refer to it. all you have to know is that when people do, they'll be able to get nice simple instructions that will lead them to the answer they are looking for.
use lots of sub headings. sub headings are easy to write. (if you can't even write the subheadings then you're really in trouble) write enough sub headings the thing is practically done. That's your first draft. Print it out. Give yourself a pat on the back.
write very quick notes under each sub heading. print it out and re-read it, judging it only for its truthfulness and its completeness. Do not parse it for grammar, style, sophistication, sexiness or anything else. Where it isn't complete, add More notes. Where it isn't truthful, make it truthful. Ugly is fine. Stupid is okay. Boring is expected. Just make it truthful and complete. Now print that out. that's your second draft. You've earned another pat on the back.
now track down your sub-editor. This is probably your wife/secretary/mother - someone who is not your boss, who loves you unconditionally, who is not as technical as you (they're NOT concerned with the facts or the completeness of what you've written.) Please with them until they agree to read through it with you. They love you unconditionally, so they will agree. They won't hate what you've written, but they'll know which problems of style are the important ones. And once you've read it through with them, you will too. The third draft's the charm. once that's done, send it out into the world. You've wasted enough time already.
Previous Topic
