From owner-freebsd-doc@FreeBSD.ORG Sat Dec 4 17:19:26 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 6E18916A4CE for ; Sat, 4 Dec 2004 17:19:26 +0000 (GMT) Received: from pi.codefab.com (pi.codefab.com [199.103.21.227]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0CE0443D39 for ; Sat, 4 Dec 2004 17:19:26 +0000 (GMT) (envelope-from cswiger@mac.com) Received: from [192.168.1.250] (pool-68-161-115-118.ny325.east.verizon.net [68.161.115.118]) by pi.codefab.com (8.12.11/8.12.11) with ESMTP id iB4HJFv4080809 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sat, 4 Dec 2004 12:19:18 -0500 (EST) Message-ID: <41B1F194.6060807@mac.com> Date: Sat, 04 Dec 2004 12:19:16 -0500 From: Chuck Swiger Organization: The Courts of Chaos User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7.3) Gecko/20040910 X-Accept-Language: en-us, en MIME-Version: 1.0 To: FreeBSD-doc@FreeBSD.org References: <20041203125024.31182375@localhost> <20041203155837.572c9ece@localhost> In-Reply-To: <20041203155837.572c9ece@localhost> X-Enigmail-Version: 0.86.1.0 X-Enigmail-Supports: pgp-inline, pgp-mime Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Status: No, hits=-4.5 required=5.5 tests=AWL,BAYES_00 autolearn=ham version=2.64 X-Spam-Checker-Version: SpamAssassin 2.64 (2004-01-11) on pi.codefab.com Subject: Re: Merging the FAQ -> handbook, build time options, proof ofconcept patch X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 04 Dec 2004 17:19:26 -0000 Hi-- I've been following this discussion with some interest and less angst, since my FreeBSD doc needs are generally satisfied. The Handbook compares well with high-quality docs such as Sun's AnswerBooks stuff. To be more precise in that comparison, the Handbook contains some very good writing and a relatively well-organized division of topics and chapters [1]; Sun's documentation is somewhat less creative in style, but is much more comprehensive in the detailed coverage of specific areas [2], and it also has a wider scope of organization. [3] ------ [1]: In particular, the Handbook is a noticably better read than the Solaris "System Administration Guide". [2]: Sun has the resources to produce 600+ pages just on the DiskSuite RAID software, or their Solstice Backup stuff, etc etc. [3]: See http://docs.sun.com. Note that it is gracefully multilingual, and the discussion in the help topics is worth a read (although buried too many clicks in). http://www.freebsd.org/docs.html or maybe http://www.freebsd.org/doc/en_US.ISO8859-1/books/ is the closest thing FreeBSD has to a "stable doc URL". Tom Rhodes wrote: > On Fri, 3 Dec 2004 13:02:12 -0600 (CST) > Mark Linimon wrote: [ ... ] >>I agree that we don't want any overlap in the FAQ and the handbook, >>or frankly for anyplace else for that matter. The overlap causes >>confusion for both users and doc committers. That's one of the >>reasons that the FAQ has rotted so badly. > > So, lemmie get this straight. > > Quick and question and answers in the faq, more thorough explinations > moved into the handbook? If you can't answer a frequent question with a paragraph or so, I would be happy if the FAQ gave a brief intro and a link to a more comprehensive description elsewhere. Whether elsewhere is in the handbook, some other article, or elsewhere on the web shouldn't matter. >>I see the FAQ serving as a "Start Here" document for people who >>are not familiar with FreeBSD; as a place for "what is it/why should >>I care/why did you do XYZ" thing. I see the handbook as "now that >>I have FreeBSD installed, how do I do XYZ". The timeslice I had to >>do the hackup job was insufficient to have gotten that across. > > Yes, I can see your point, valid it is. Heh. My take on this is that whenever someone answers a question on a mailing list with "This is a FAQ", such material actually ought to be in the FAQ. In particular, searching the FAQ either via the find mechanism in one's browser or via http://www.freebsd.org/search/search.html about an error like "ad0: WARNING - WRITE_DMA interrupt was seen but timeout fired LBA=2928095" produces nothing. Another example would be searching for "why does ruby dump core when I run portupgrade?"... [ ... ] > We need to close this matter and get back to work doing useful > and good things. So, we have one problem and we need to choose > what to do: > > Move most of the FAQ and keep the FAQ simple, > Move all of the FAQ and either have it all in the handbook or as 1 file, > Kill the FAQ off and start it a new. #1 seems to be the closest to my thoughts. I can't say I find the current FAQ to be very useful since it hides stuff too many clicks in and it doesn't reward searching especially well. I would be happier with a plain-text FAQ in Q&A format, or as a Docbook article rather than a book with subchapters. The sendmail FAQ and the INN FAQ struck me as good FAQs, in that they can be used successfully even to someone using less or i-search in Emacs on the ASCII version. Newer versions use a split HTML layout, but at least put all of the questions in one place that can be searched for easily. -- -Chuck