Yet More Tips For Documentation Writers (Writing For Money!)
Dec 13, 2008, 04:32 (0 Talkback[s])
(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."
Complete
Story
Related Stories:
- More Tips For Documentation Writers (You Too, Ace Coders)(Dec 10, 2008)
- Tips For Documentation Writers (This Means You Too, Ace Coders)(Dec 04, 2008)
- Testing Grails: Squash Bugs and Build Executable Documentation(Oct 17, 2008)
- The Open Source Principles of Participation(Sep 13, 2008)
- Editor's Note: Chrome Comic Books, Yugos, Our New Global Overlords(Sep 05, 2008)
- Learning Doxygen for Source Code Documentation(Aug 06, 2008)
