From owner-freebsd-doc@FreeBSD.ORG Tue Jul 20 18:25:52 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 1559416A4CE; Tue, 20 Jul 2004 18:25:52 +0000 (GMT) Received: from abigail.blackend.org (blackend.org [212.11.35.229]) by mx1.FreeBSD.org (Postfix) with ESMTP id E429F43D60; Tue, 20 Jul 2004 18:25:50 +0000 (GMT) (envelope-from marc@blackend.org) Received: from abigail.blackend.org (localhost [127.0.0.1]) i6KIPkH5076931; Tue, 20 Jul 2004 20:25:46 +0200 (CEST) (envelope-from marc@abigail.blackend.org) Received: (from marc@localhost) by abigail.blackend.org (8.12.11/8.12.11/Submit) id i6KIPkd3076930; Tue, 20 Jul 2004 20:25:46 +0200 (CEST) (envelope-from marc) Date: Tue, 20 Jul 2004 20:25:45 +0200 From: Marc Fonvieille To: Tom Rhodes Message-ID: <20040720182545.GA76560@abigail.blackend.org> References: <20040719100354.GA90972@hub.freebsd.org> <20040720103432.GA64597@clan.nothing-going-on.org> <20040720104501.GB5405@hub.freebsd.org> <20040720124337.GA8096@electra.cse.Buffalo.EDU> <20040720140759.GA69951@abigail.blackend.org> <20040720144725.GE17260@hub.freebsd.org> <20040720132604.2f0ced26@localhost> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20040720132604.2f0ced26@localhost> User-Agent: Mutt/1.4.2.1i X-Useless-Header: blackend.org X-Operating-System: FreeBSD 4.10-PRERELEASE cc: Nik Clayton cc: Murray Stokely cc: doc@FreeBSD.org cc: Ken Smith Subject: Re: The FAQ (was Re: Creating an Admin Handbook) 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: Tue, 20 Jul 2004 18:25:52 -0000 On Tue, Jul 20, 2004 at 01:26:04PM -0400, Tom Rhodes wrote: > On Tue, 20 Jul 2004 14:47:25 +0000 > Murray Stokely wrote: > > > On Tue, Jul 20, 2004 at 04:07:59PM +0200, Marc Fonvieille wrote: > > > Why FAQ is not really used/read? It's difficult to answer to that > > > question but I assume cause it's less "famous" and cause the human being > > > is lazy, it's an effort to go read the Handbook, so switching to the FAQ > > > is too much :) and since the FAQ is not linked (and not detailled) from > > > the Handbook, people ignore it. It's not wrong to tell that a lot of > > > people ignore the FAQ exists. (I know there is an old project to > > > link/merge the FAQ in a dynamic way with the Handbook) > > > The more you split a document the more you will fell in a such > > > situation. > > > > I don't think it's a fair comparison since the FAQ is written in a > > much less formal style than the rest of our documentation. It is also > > HUGE for a 'FAQ' and people just aren't used to wading through such a > > huge list of boring error messages that don't apply to them, and > > information about pieces of hardware they've never heard of before > > they get to something that is relevant for them. > > Most user *I* have conversations with have stated that they > avoid the FAQ completely in favor of the more thorough > instruction provided by the handbook. Only after double > checking their steps with the handbook will they check the > FAQ, google, lists, etc. > I was not clear in my message: of course the FAQ is not a detailled documentation to set up your system etc. it's a FAQ. On this point you cannot compare it with the Handbook. I was talking about the fact people hardly use/read it. A lot of questions asked on the various mailing lists, newsgroups, etc. around the world are still the same and are documented in the FAQ: for example allowing ordinary users to mount a disk, booting with the win2k/xp/etc. loader, recovering a forgotten root password, etc... As I said it "seems" people, when they read a doc, only read the Handbook. I was just "afraid" of the fact splits could give birth of docs too much different, I mean with a an important separation between each book, the reader spending his time switching between books or reading one book only. It's why I think having a general table of contents may be a good idea. Marc Marc