:Yet More Tips For Documentation Writers (Writing For Money!)
Yet More Tips For Documentation Writers (Writing For Money!) Dec 13, 2008, 04 :32 UTC (0 Talkback[s]) (3236 reads) (Other stories by Carla Schroder)
"The dive right into the hands-on; give readers something to do right away with minimal exposition. Wrap up with more detailed explanations of theory and concepts, and references to additional material.
"Keep articles narrowly focused--don't try to cram too much into a single piece. It's better to address a small task in detail than to cover a lot of ground too shallowly. You can always turn a long, complex topic into a series of nice bite-sized chunks.
"Your readers will adore you if you don't shy away from the hard parts. If you find yourself wanting to write "see the man page for details" instead of outlining the steps yourself, take another look and see if you're trying to take the easy way out. The only place "see foo for more information" belongs is at the end in an additional references section."
