> 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.