[Date Prev][Date Next]
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
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/