Resistance to documentation? (was Re: Pull in upstream before 9.1
code freeze?)
Dave Hayes
dave at jetcafe.org
Tue Jul 17 20:56:34 UTC 2012
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.
More information about the freebsd-hackers
mailing list