The FreeBSD Handbook, in Wiki form.

[Randy Pratt]

On Wed, 04 May 2005 09:12:09 -0400
"MikeM" <zlists at mgm51.com> wrote:

> On 5/3/2005 at 5:29 PM Benjamin Keating wrote:
> 
> |A wiki would eliminate that bottle neck (PR).
> |Some parts are out of date. Others fail to mention FAQ , etc. that
> |could really help. For instance, the NAT/DHCP articles could easily
> |include a 'typical home user' HOWTO rather then tricking the user into
> |reading that one line where it says you have to recompile your kernel
> |with IPFIREWALL support.
> |
> |Things like that bring noise to this mailing list. Idon't know about
> |you but I'd rather just add my new found info to the site rather find
> |a PR addy, submit it and wait for it to be added. We have software
> |that does this now. Lets use it! :)
>  =============
> 
> When I found a spot in the Handbook that was a bit sparce, I send in an
> email describing what I was looking for, what I found, and what i expected
> to find.  The Handbook was updated within a few days, and the update was
> much better than what I could have written.
> 
> 
> Maybe a wiki would supplement the Handbook, rather than replace it.
> 

There's some benefits to the present documentation approach that are
being overlooked.

It has a revision control system.  This enables you to obtain a
version of a handbook for any given date thru CVS.  This magic is
also what allows you to update your local documentation and use a
minimum of bandwidth.

It can produce output in a number of formats (HTML, PDF, PS, etc)
from a single set of sources.  Don't forget that the FreeBSD Handbook
is also published occasionally from these same sources.

The documentation is available in a variety of languages due to
the efforts of the translation teams.  They use the revision control
system to determine when updated translations are needed.

The documentation is available as part of the system and web access
isn't required.  It can also be freely distributed whereas I'm not
sure who owns the content of a wiki.

As others have mentioned, peer review is very important especially
with documentation.  The wording and syntax needs to be very clear
since many users do not speak english as a first language.

I'm probably overlooking some other aspects of the benefits but
the present system does produce documentation that many consider
to be the best of any comprable OS's.

Granted, the centralized approach to documentation doesn't produce
instant gratification that a wiki might but it seems to lend itself
well for a variety of uses in a quality manner.  In the end, its
the content that is important and not the method.  It probably
doesn't take any more time on the part of a user to fill out a
wiki-form than it takes to send-pr.

There might be some niche that a wiki might be useful but I'd
need to see a rough implementation showing how it addresses
something that is lacking in the present method.  There's always
room for improvement.

I just thought I'd throw a few things out for thought before we
continue building the Big Bikeshed ;-)

Randy
--