From owner-freebsd-doc Mon Jan 21 21:33:17 2002 Delivered-To: freebsd-doc@freebsd.org Received: from lists.blarg.net (lists.blarg.net [206.124.128.17]) by hub.freebsd.org (Postfix) with ESMTP id BC2E437B400 for ; Mon, 21 Jan 2002 21:33:14 -0800 (PST) Received: from thig.blarg.net (thig.blarg.net [206.124.128.18]) by lists.blarg.net (Postfix) with ESMTP id 4E175BD94; Mon, 21 Jan 2002 21:33:14 -0800 (PST) Received: from localhost.localdomain ([206.124.139.115]) by thig.blarg.net (8.9.3/8.9.3) with ESMTP id VAA14795; Mon, 21 Jan 2002 21:33:13 -0800 Received: (from jojo@localhost) by localhost.localdomain (8.11.6/8.11.3) id g0M5aVZ01424; Mon, 21 Jan 2002 21:36:31 -0800 (PST) (envelope-from swear@blarg.net) To: Michael Lucas Cc: doc@FreeBSD.ORG Subject: Re: Practicalities of FAQ->Handbook migrations References: <20020121140800.A54903@blackhelicopters.org> <20020121215313.K18715@clan.nothing-going-on.org> <20020121174711.A56388@blackhelicopters.org> From: swear@blarg.net (Gary W. Swearingen) Date: 21 Jan 2002 21:36:31 -0800 In-Reply-To: <20020121174711.A56388@blackhelicopters.org> Message-ID: Lines: 37 User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.1 (Cuyahoga Valley) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org Michael Lucas writes: > I suppose we could. I'd personally prefer a single book with > everything in it, but will obey the consensus of the group. > > Whaddaya think, folks? Ideally the handbook is comprehensive enough that the FAQ is not needed, except perhaps as an alternative form of TOC/index into the handbook. But as long as there are both a Handbook and a FAQ, and they are equally well organized for finding info, the only reason I see to move info to the Handbook is to eliminate duplication (so there is less to maintain and less that users must read), and not to just make it smaller. But since there has been and should be more investment of effort in organizing the handbook, it makes sense to move stuff there. When it's hard to find a place in the Handbook for something, I'd think that's an indication that the Handbook organization needs expansion. It would be hard work (both design and implementation), but I think it's the only thing that would make the move of info from the FAQ to the Handbook valuable. A catch-all chapter or book is no better than leaving the stuff in the FAQ, except that you'd then have essentially have three places to look for help (plus the man pages, articles, READMEs, etc). P.S. Maybe more though needs to be given to multi-level presentation of info; "Quick Start", "Cook-book of SA Tasks", etc., but I think it's too much work and that level of stuff is best left to articles. For now, it would be better to have a consistent level of rather dense information. (Maybe with some embedded examples and recipes.) I.e., I don't see the FAQ as a place for an alternate level of info. P.P.S. I'd like the FAQ better if the top TOC had all the questions instead of burying them at the start of each chapter. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message