Linux Today: Linux News On Internet Time.
Search Linux Today
Linux News Sections:  Developer -  High Performance -  Infrastructure -  IT Management -  Security -  Storage -
Linux Today Navigation
LT Home
Contribute
Contribute
Link to Us
Linux Jobs


Top White Papers

More on LinuxToday


Linux Bug #1: Bad Documentation (part 2)

Nov 20, 2009, 03:03 (1 Talkback[s])
(Other stories by Carla Schroder)

"In Part 1 I talked about the messy state of Linux documentation, and how telling users to rely on Google is not documentation. Good documentation is equally important as good code. Sometimes there is this attitude that developer time is more valuable and important than user or potential contributor time. I suppose it depends on how much a particular project wants users and contributors; the more friendly and helpful on-ramps into a project, the more users and contributors. Good documentation is a big step towards quality control; when everything is documented, including reasons why something is done a certain way, it's less likely to be forgotten, which increases efficiency.

"Getting started is probably the biggest hurdle, and once that first set of docs is completed they go into maintenance mode and need only changes and updates. I have a theory that good documentation discipline also encourages good development discipline, and fewer senseless changes that tend to vex users. Like moving a button or changing a command name, or re-organizing menus-- having to document all these things means taking another look at them and deciding if they are really necessary."

Complete Story

Related Stories: