[Scrollkeeper-devel] Re: draft article, for review

[Nik C. <ni...@fr...>]

Rich,

On Mon, Nov 27, 2000 at 11:09:54AM -0800, Rich Morin wrote:
> I have written up some recent experiences with FreeBSD documentation
> for my column (Silicon Carny) in SunWorld (http://www.sunworld.com).
> The column also attempts to summarize the aims of the ScrollKeeper
> and Meta Projects.
> 
> If you would like to look at the draft I'm submitting, take a look at
> http://www.cfcl.com/rdm/SC.200012.1.  Please send me email (in the
> next few days) about any problems you notice.  I should be able to
> squeeze in a few changes during final edit...

I'm keeping the cc's in place for this, because this is something I want
to reiterate to the commentators and lurkers on the FreeBSD-doc mailing
list (and the various Linux doc people on the ScrollKeeper list will
probably agree).

We're in complete agreement about the need for better documentation, and
the requirement for better searching and indexing tools.  Of this latter
requirement, I have high hopes for ScrollKeeper (once we've finished
batting around some of the design decisions).

Your choice of make.conf is perhaps a little unfortunate, as in the past
few weeks someone else has had exactly the same problem you had.  They
also realised that a make.conf manual page would be a good thing to have
for the reasons you specify in your article.

So, they wrote one, put together a PR (Problem Report, or Patch Report,
depending on who you listen to), visible at

    http://www.FreeBSD.org/cgi/query-pr.cgi?pr=22676

As you can see, this was then kicked back and forth a bit on the mailing
list, changes were made, and then it was committed to FreeBSD.  So
FreeBSD, thanks to the actions of one of its users, now has a
make.conf(5) manual page.

I don't doubt that there are other areas of the system that need further
documentation and explanation.  It's an unfortunate fact of life for all
of us that there are this >           < many things to do, and this > <
much time in which to do them.  This is why the FreeBSD project is very
open to receiving PRs, and I do my level best to bring people in to the
doc project as soon as they demonstrate that they can generate good PRs
and won't need an excessive amount of handholding.  In the recent past
this includes people like

    Bruce Mah
    Ben Smithurst
    Mark Ovens
    Daniel Harris
    Kazuo Horikawa
    Hiroki Sato
    Alexander Langer

and many others (Neil, Sheldon, Jeroen, the list is long, and an
omission just means I haven't got time to work through CVSROOT/access).

This is how the process works -- people find problems, fix them, and
submit patches.  Sometimes the people finding the problem are already
committers, but a lot of the time it's FreeBSD users.  And with the best
will in the world, a PR with a patch is a hell of a lot easier for a
committer to deal with than a message saying that something needs
fixing.

[ For example, the fact that sysinstall doesn't know about the
  new documentation packages yet -- I know this is a problem, as do
  people following this mailing list.  But unless someone else steps up
  to the plate (anyone!) with patches, the problem's going to have to
  wait until I've got the requisite 12 clear hours to sit down with the
  sysinstall code and write the glue. ]

N
-- 
Internet connection, $19.95 a month.  Computer, $799.95.  Modem, $149.95.
Telephone line, $24.95 a month.  Software, free.  USENET transmission,
hundreds if not thousands of dollars.  Thinking before posting, priceless.
Somethings in life you can't buy.  For everything else, there's MasterCard.
  -- Graham Reed, in the Scary Devil Monastery