Date: Tue, 17 Jul 2012 15:14:04 -0700 From: Doug Barton <dougb@FreeBSD.org> To: Dave Hayes <dave@jetcafe.org> Cc: freebsd-hackers@freebsd.org Subject: Re: Resistance to documentation? (was Re: Pull in upstream before 9.1 code freeze?) Message-ID: <5005E3AC.7050001@FreeBSD.org> In-Reply-To: <5005D181.8080709@jetcafe.org> References: <20120717183221.298430@gmx.com> <20120717153505.42633535@bhuda.mired.org> <5005D181.8080709@jetcafe.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On 07/17/2012 01:56 PM, Dave Hayes wrote: > 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. Writing code is more fun than documenting it. People who are good at documenting other people's code usually go down 2 paths ... either they become very good at it and expect to be well paid for their services, or they realize that writing code is more fun than documenting it. That said, historically as a project we have placed very high value on attracting people who are good at writing good code, and not placed a high value on documentation. That's not to say that we don't value the people who *do* write our documentation, but if it comes to a choice between good code with no documentation, or no code, we have historically chosen the former. This is true to the extent that when I suggested to a new committer that they should have waited to add a new project until the man pages were written I got torn a new one by my fellow committers, and told that I was 'discouraging contributions' and 'bad for morale.' > 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. Resistance is not accurate. Indifference is a better description. > Some sources of this are: I rarely read the handbook So now that we've discussed *our* shortcomings, let's discuss yours. :) Read the handbook. Seriously. The FAQ is stale, and needs attention, but the FreeBSD Handbook is top-quality stuff. It has some cobwebby bits, and if you find them, file PRs to bring it to our attention. But you can't on one hand say that we resist documentation, and then on the other hand admit that you haven't read our most important example. > ... 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 ). So we're back to the area where we are indeed weak. I have pushed and pushed (both privately and publicly) for us to get better in this area, and am constantly told that what I'm asking for is foolish and/or unnecessary. We really do need better design documents, and plans to change critical parts of the system should be better documented in advance. But frankly, this is incredibly unlikely to happen without a major change in the values system of the project as a whole; and the last core election made it pretty clear that it's not likely to happen any time soon. > 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. Not only is the perception reasonable, but the process of writing out such documentation (different from handbook-style docs, or even man pages) often helps clarify both the actual proposed design, and the current state of things. It's a shame that we don't have a culture that not only encourages this, but requires it. However, we don't; and aren't ever likely to. Doug
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?5005E3AC.7050001>