Date: Wed, 4 May 2005 11:15:23 -0400 From: Randy Pratt <rpratt1950@earthlink.net> To: "MikeM" <zlists@mgm51.com> Cc: freebsd-questions@freebsd.org Subject: Re: The FreeBSD Handbook, in Wiki form. Message-ID: <20050504111523.335e3592.rpratt1950@earthlink.net> In-Reply-To: <200505040912090592.03B6BBC1@sentry.24cl.com> References: <781e2bc0050503170031a960fd@mail.gmail.com> <20050504001546.GA64854@xor.obsecurity.org> <781e2bc005050317295898d640@mail.gmail.com> <200505040912090592.03B6BBC1@sentry.24cl.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, 04 May 2005 09:12:09 -0400 "MikeM" <zlists@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 --
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20050504111523.335e3592.rpratt1950>