[Date Prev][Date Next] [Chronological] [Thread] [Top]

Documentation

Dave Horsfall wrote:
Which in turn illustrates the dichotomy of the problem: those in the best position to document something i.e. the developers themselves are the very ones who cannot (because they're too busy) or should not (because they are too close to it, and take things for granted). This got drilled into me around 25 years ago, at a DEC device driver course.

I think that's a false dichotomy. Software has bugs, we file bug reports, and the bugs get fixed. If docs are missing something because a point has been taken for granted, it's no different - someone files a bug report against the doc, and the doc bug gets fixed. The process is always the same, and it's driven by the same thing - user feedback. No bug reports, no fixes.

The point about developers being too busy is only peripherally relevant - everything in the Project was contributed at some point or another. Yes, developers are busy; no, you should not expect "someone else" to contribute everything. If you want something addressed, it's up to you to make it happen.

On the other hand, Open Source has no official Documentation Department.

On the gripping hand, end-users will document that which they do not understand...

Which is why I always harp on these points:
1) don't blindly follow advice that is given without an explanation of the rationale behind the advice.
2) don't give advice without an explanation.
3) don't create documentation in a vacuum - submit it to the Project so that it can be reviewed, corrected, and incorporated.

Easy answers tend to be the least useful in the long run. "RTFM" answers are given for a reason - to make you think, and to make you learn. The problem with most HOWTOs (the ones that aren't completely wrong, anyway) is they tend to just list a sequence of steps, without any explanation of why those steps work, why their particular sequence was chosen, etc.

As a quick example, if you were faced with a black box that takes one number as input and spits out another number as output, and you were given a sample set of inputs and outputs:
1, 2, 3, 4, 5, 6, 7, 8, 9
1, 0, 9, 0, 25, 0, 49, 0, 81
it may not be immediately obvious to you why those outputs are as they are. If someone then asks you "what will be the output for an input of 15" you might be hard-pressed to come up with the answer.

On the other hand, if someone were to tell you "the rule for this black box is that for any even number, the output is zero, and for any odd number, the output is the square of the input" then you can easily apply that rule to any arbitrary input.

HOWTOs without detailed explanations are like the black box with just a short list of data points. They don't teach you anything, they only give you a fixed set of answers to a fixed set of questions. When you're faced with a new question that's not on their list, you're lost.

It's always important to understand the reasons behind the answers.
--
  -- Howard Chu
  Chief Architect, Symas Corp.  http://www.symas.com
  Director, Highland Sun        http://highlandsun.com/hyc
  Chief Architect, OpenLDAP     http://www.openldap.org/project/