From owner-freebsd-doc@FreeBSD.ORG Sun Nov 28 21:40:23 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 447EF16A4CE; Sun, 28 Nov 2004 21:40:23 +0000 (GMT) Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66]) by mx1.FreeBSD.org (Postfix) with ESMTP id 080CA43D1F; Sun, 28 Nov 2004 21:40:21 +0000 (GMT) (envelope-from linimon@lonesome.com) Received: by mail.soaustin.net (Postfix, from userid 502) id 8525C148D7; Sun, 28 Nov 2004 15:40:21 -0600 (CST) Date: Sun, 28 Nov 2004 15:40:21 -0600 (CST) From: Mark Linimon X-X-Sender: linimon@pancho To: Marc Fonvieille In-Reply-To: <20041128211444.GC6664@abigail.blackend.org> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII cc: freebsd-doc@FreeBSD.org cc: "Simon L. Nielsen" Subject: Re: Doc BoF at EuroBSDCon 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: Sun, 28 Nov 2004 21:40:23 -0000 On Sun, 28 Nov 2004, Marc Fonvieille wrote: > I see one important thing missing in this list, an important thing for > the reader: the merge of the FAQ in the Handbook. I'd put that on top > of the list, very important informations are in the FAQ and people often > miss them cause they are in another document, etc. After tangling with the FAQ on several occasions, here's what I would like to see happen: - the FAQ should remain -- but with a tiny subset of the text that's in there, e.g. things at the level of "what is FreeBSD". These should be questions that answer "what" and "where". - questions that answer "how" should be either a) removed, or b) turned into a crossref into some other file, and the text migrated there. (example: the ppp chapter). Whather that's the Handbook, or e.g. a separate ppp-howto, I don't have an opinion. (Perhaps there are cases where one or the other is appropriate). - anything that's of the form "does XYZ card work" should be a crossref into the release notes. - anything that's of the form "what does terminology X mean" should be a crossref into the Glossary. If the Glossary isn't its own page, it should be. - the bibliography should become its own page. The "best of all possible worlds"? That would be to take the things of the form "I'm having trouble with my XYZ card" and turn them into some kind of knowledge-base thing that would be much more lightweight (e.g. not require DocBook) -- not so much because I or anyone else here is allergice to DocBook, but to lower the 'barrier of entry' so that people who are not on the doc project could contribute to it. This would leave the handbook as a "start here and then do this" and this new, theoretical, resource as the "I'm having a problem" resource. Regardless of this long-term pipe dream, IMHO the above suggestions ought to be considered in the short-to-medium term. Yes, I'll summarize any consensus that arises about the FAQ and put it up on the wiki. mcl