ISerializable - Roy Osherove's Blog

As a former C++ developer, I can safely say...'I feel your pain'.. :-)
I'll be happy to help with the help file of The Regulator... let me know..

I'm starting to appreciate that technical writing class I had to take in college. I guess that's one benefit of getting a CE degree (that's Civil Engineering, not Computer Engineering).

If I had more free time I'd give it a shot but I'm already working way too much for my wife to tollerate me doing freebie work on the side. Sorry.

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 mroe 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 earnt 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.

cheers
leon bambrick
www16.brinkster.com/messydesk/db/index.asp

Thanks for your honesty...and respect. As HP info engineer (what they called tech writers) John Bowie from Colorado says, "Software engineers code for the CPU, but information engineers [read: technical communicators] code for the human mind." And fo us humans, it's not either/or, in/out, 1/0...it's more "it depends."
Another key task, of course, is to know your users. Find out what your users really need, by watching them attempt to do their jobs. Watching users is the best input you can get to determine what to write.
Best of luck!
joe
Joe Sokohl
facetime.blogspot.com

Technical writing isn't a talent that some people are born with, it's a skill with learned expertise (like software development). The more you know, the easier it becomes.

Keep working at it. You'll be fine. In the meantime, look at online resources that can help (like the Tech Comm Library, http://tc.eserver.org/).

As a technical writer, I share your pain. Writing Help files can be challenging. It not only can be tough trying to deciding how to filter the information you want to include in online Help (just dumping a user manual into a Help format is the lazy way out), but it's also tough to massage that information so that it's not too verbose or too sparse.

It takes time, it takes practice. And, even then, it's not always that easy.