Yet More Tips For Documentation Writers (Writing For Money!)

Written By
CS
Carla Schroder
Dec 13, 2008

“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

CS

Carla Schroder

Linux Today Logo

LinuxToday is a trusted, contributor-driven news resource supporting all types of Linux users. Our thriving international community engages with us through social media and frequent content contributions aimed at solving problems ranging from personal computing to enterprise-level IT operations. LinuxToday serves as a home for a community that struggles to find comparable information elsewhere on the web.

Property of TechnologyAdvice. © 2026 TechnologyAdvice. All Rights Reserved

Advertiser Disclosure: Some of the products that appear on this site are from companies from which TechnologyAdvice receives compensation. This compensation may impact how and where products appear on this site including, for example, the order in which they appear. TechnologyAdvice does not include all companies or all types of products available in the marketplace.