Date: Tue, 17 Jul 2012 13:56:33 -0700 From: Dave Hayes <dave@jetcafe.org> To: freebsd-hackers@freebsd.org Subject: Resistance to documentation? (was Re: Pull in upstream before 9.1 code freeze?) Message-ID: <5005D181.8080709@jetcafe.org> In-Reply-To: <20120717153505.42633535@bhuda.mired.org> References: <20120717183221.298430@gmx.com> <20120717153505.42633535@bhuda.mired.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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@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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?5005D181.8080709>