Linux Today: Linux News On Internet Time.

More Tips For Documentation Writers (You Too, Ace Coders)

Dec 10, 2008, 00:05 (2 Talkback[s])
(Other stories by Carla Schroder)

"An unfortunate amount of computer documentation is so terse it seems as though the writer had to pay by the word. While it is possible to over-explain, that's hardly ever a problem. With computers we're dealing mostly in abstract concepts, so don't be shy about spelling out even details that seem too obvious and basic, because to a lot of readers they won't be obvious and basic.

"A picture is worth a thousand words, and so are screenshots showing exactly what you're talking about. For command line programs it's even easier than creating screenshots, just copy and paste the text. You want to be as literal as possible, because computers demand precise literal commands. They can't read your intent or waving hands, only what you type."

Complete Story

Related Stories: