Linux Bug #1: Bad Documentation (part 2)

“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