Resistance to documentation? (was Re: Pull in upstream before 9.1 code freeze?)

[Dave Hayes]

On 07/17/12 12:35, Mike Meyer wrote:
> I'm not going to do this - this is the kind of thing that makes me
> loathe Linux. But if you want this functionality in your/the base
> system, your first step is clear - write the WTF program! Until that
> exists, the rest is just pointless debating.

I think this is unintentionally specious reasoning. No offense intended. :)

The program itself is fairly trivial to write. It's the -content- that 
is important to the perceived usability of the tool. I do not believe 
the content can be written by one person alone; this would be a 
community effort. Without the content, most everyone will declare the 
tool useless, the experiment a failure, and it will be business as usual.

So it's really not possible to write the tool and associated 
documentation "myself". Otherwise I would. The "pointless debating" is 
really an attempt to get a critical mass of knowledgeable developers to 
agree to participate in creating this tool. There seems to be an equal 
and opposing mass that feels we should dig for this information 
ourselves and the existence of a helpful tool to do this is a blight on 
the operating system.

The problem actually has a deeper idea, and this is why I changed the 
subject line.

I've been using FreeBSD since the 90s. My perception (over many years of 
observation) is that the FreeBSD people most able to document what 
exists and how to use it seem to also have the greatest resistance to 
writing any documentation. Perception is usually subjective, and I'm not 
going to try to prove this or claim objective truth here...I could very 
well be objectively incorrect. Perhaps it's more general; it seems to me 
at best that this community resists documentation and explanation in the 
general case.

Some sources of this are: I rarely read the handbook and find that the 
procedures or tools work as advertised, or that there wasn't some better 
tool or idea I "should have just known to do". I likely miss some best 
practices because...the information is not out there and sometimes 
asking anything is met with stoic silence (e.g. how
does libgeom work, especially the XML stuff...for that matter a good 
detailed document on geom(8) with examples and best practices ).

This perception troubles me because, at least in my mind, a good 
developer also documents the work and provides some sort of link or 
summary for people who are running production or near-production 
systems. I really don't understand why I have this perception, nor is it 
logical that the perception should exist in the first place.

It remains nonetheless.
-- 
Dave Hayes - Consultant - Altadena CA, USA - dave at jetcafe.org
 >>>> *The opinions expressed above are entirely my own* <<<<

Nasrudin was sitting talking with a friend as dusk
fell. "Light a candle", the man said, "because it is dark
now. There is one just by your left side."  "How can I tell
my right from my left in the dark, you fool?" came the
reply.