Writing Good Software Documentation

[Wordzilla]

Good documentation may exclude in many cases the need for further forms of technical support. It is, however, not easy to write. One of the reasons why this happens is that it is difficult for shareware authors or other software developers to put themselves into the users ’ shoes, since they are already thoroughly familiar with the application.

[mouser]

nice find. 

[brownstudy]

I've been tech writing for umpty-ump years. My two tips for newbies:

1. The web has taught people to scan, not read. Write in short squibs, keep the humor to a minimum unless you're really funny, keep it scannable. Save the long text passages for the advanced topic where the interested user will be expected to invest their time to learn the good stuff.

2. If you find yourself dumping every scrap of info you have into the documentation, then you haven't decided who the audience is, what they'll use the info for, or you don't understand the product. Figure out which one is the real problem. Your job as the writer is to select and contextualize the information so it goes down like chocolate milk, or at least doesn't cause cognitive pain. It's not the user's job to sift through the documentaiton to find the good stuff, it's your job.

I have some delicious links on tech writing here: http://delicious.com/brownstudy/techwriting

A really really interesting longish read is this essay on adapting Agile strategies for writing agile documentation:  http://www.agilemodeling.com/essays/agileDocumentation.htm

[tinjaw]

brownstudy,

That is some excellent advice. And not just for n00bs either.