Re: Documentation

[Greg Martin <gmartin@gmartin.org>]

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.

\\Greg