From owner-freebsd-hackers@FreeBSD.ORG Wed Dec 21 16:01:40 2005 Return-Path: X-Original-To: hackers@freebsd.org Delivered-To: freebsd-hackers@FreeBSD.ORG Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id C9D0716A420 for ; Wed, 21 Dec 2005 16:01:40 +0000 (GMT) (envelope-from hakuchi@www.liukuma.net) Received: from www.liukuma.net (www.liukuma.net [62.220.235.15]) by mx1.FreeBSD.org (Postfix) with ESMTP id 15C2D43D45 for ; Wed, 21 Dec 2005 16:01:38 +0000 (GMT) (envelope-from hakuchi@www.liukuma.net) Received: by www.liukuma.net (Postfix, from userid 1021) id 7EE8C5943; Wed, 21 Dec 2005 18:01:37 +0200 (EET) Received: from localhost (localhost [127.0.0.1]) by www.liukuma.net (Postfix) with ESMTP id 7C6D556C6 for ; Wed, 21 Dec 2005 18:01:37 +0200 (EET) Date: Wed, 21 Dec 2005 18:01:37 +0200 (EET) From: Juhana Tahvanainen To: hackers@freebsd.org In-Reply-To: <20051220142254.GD68989@submonkey.net> Message-ID: <20051221161520.O1593@www.liukuma.net> References: <43A26FFB.9080405@samsco.org> <200512190934.jBJ9YNhX022376@musashi.et.bocholt.fh-gelsenkirchen.de> <20051220142254.GD68989@submonkey.net> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Mailman-Approved-At: Wed, 21 Dec 2005 16:11:33 +0000 Cc: Subject: Re: My wish list for 6.1 X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 21 Dec 2005 16:01:41 -0000 how about: FreeBSD-Handbook-General (guaranteed to work with all FreeBSD systems, doesn't include stuff in FreeBSD-Handbook-BRANCH.x) FreeBSD-Handbook-4.x (guaranteed to work with 4.x branch, doesn't include stuff in FreeBSD-Handbook-General) FreeBSD-Handbook-5.x (guaranteed to work with 5.x branch, doesn't include stuff in FreeBSD-Handbook-General) FreeBSD-Handbook-6.x (guaranteed to work with 6.x branch, doesn't include stuff in FreeBSD-Handbook-General) ... this way layered information is minimalized and there is clear path to find something out. FreeBSD-Handbook-General is rather fixed once ready, only maintenance needed is when some future release doesnt support something anymore, that is removed and moved to FreeBSD-Handbook-BRANCH.x. FreeBSD-Handbook-BRANCH.x deals with branch in case from installation to use, having links to FreeBSD-Handbook-General when needed. FreeBSD-Handbook-BRANCH.x can also have real-life examples and comments, so need for FAQ should be covered. dunno if that is any more clear but what there is out there now, is a mess. ---J On Tue, 20 Dec 2005, Ceri Davies wrote: > On Mon, Dec 19, 2005 at 10:34:23AM +0100, Dirk GOUDERS wrote: >> >>> 3. Full review and update of the install docs, handbook, FAQ, etc. >>> There are sections that are embarrassingly out of date (one section of >>> the handbook apparently states that we only support a single brand of >>> wifi cards). A co-worker of mine tried to install 6.0 using just the >>> handbook install guide, and discovered that it really doesn't match >>> reality anymore, in both big and small ways. Contact me directly if >>> you would like his list of comments. >> >> I am wondering if it wouldn't be advantageous to have "versioned" >> documents that just cover one specific release and not to cover all >> realeases in single documents. >> >> I could imagine that it is harder to cover everything in single >> documents than to perhaps copy the existing documentation when a new >> branch is created and edit it to match just the new release. >> >> Maybe, I do not realize how much more work this would be but it would >> probably enforce regular reviews of the documentation and the readers >> would benefit from it. > > This is exactly the idea that I have been pimping to anyone who will > listen for the last three months or so. I also think that it is > advantageous for users who are using, say 4.2, to be able to find > documentation for 4.2 without having to interpret a nest of "if you have > 4.x do this, if 5.0 through 5.3 do that, else do the other". I don't > think it's a lot of work to just branch the handbook (and FAQ > if we decide to keep it) - in fact, for me, it would be a definite win - > at release time, but it just doesn't seem to be what other people want > done. > > I would encourage those interested to ask about it on doc@. > > Ceri > -- > Only two things are infinite, the universe and human stupidity, and I'm > not sure about the former. -- Einstein (attrib.) >