Linux Today: Linux News On Internet Time.

More on LinuxToday

Linux Bug #1: Bad Documentation (part 2)

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


Re-Imagining Linux Platforms to Meet the Needs of Cloud Service Providers

"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: