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

Re: Documentation

Howard Chu wrote:
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.
On the other hand, having a howTo get you started on the road to investigation can be a good thing. For me, the path to LDAP knowledge was not best started with a walk through slapd.conf. A running server with basic config can allow you to investigate LDAP at an appropriate level. You may be "lost" when you get to your first tough question, but you are lost in the middle of a highway with a bunch of signs telling you where to head for answers. No HowTo is created in a vacuum. More knowledge can be found at the end of the google path when you are ready.

Also, when you are trying to learn to fish, you are probably not ready to understand the workings of the reel, how to make lead weights and to tie a perfect knot.

My point is that there is more than one way to learn.  Options are good.