[Date Prev][Date Next]
Howard Chu wrote:
Dave Horsfall wrote:
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.
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
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
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.
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.