From owner-freebsd-doc@FreeBSD.ORG Wed Aug 20 12:10:57 2003 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 1C0C916A4BF; Wed, 20 Aug 2003 12:10:57 -0700 (PDT) Received: from rwcrmhc12.comcast.net (rwcrmhc12.comcast.net [216.148.227.85]) by mx1.FreeBSD.org (Postfix) with ESMTP id 545D443F85; Wed, 20 Aug 2003 12:10:56 -0700 (PDT) (envelope-from underway@comcast.net) Received: from localhost.localdomain (12-230-74-101.client.attbi.com[12.230.74.101](untrusted sender)) by attbi.com (rwcrmhc12) with ESMTP id <20030820190635014000btsje>; Wed, 20 Aug 2003 19:06:35 +0000 Received: from localhost.localdomain (localhost [127.0.0.1]) by localhost.localdomain (8.12.9/8.12.9) with ESMTP id h7KJ6JSE069575; Wed, 20 Aug 2003 12:06:20 -0700 (PDT) (envelope-from underway@comcast.net) Received: (from jojo@localhost) by localhost.localdomain (8.12.9/8.12.9/Submit) id h7KJ6ES1069574; Wed, 20 Aug 2003 12:06:14 -0700 (PDT) (envelope-from underway@comcast.net) To: Tom Rhodes References: <20030820110031.6953360b.trhodes@FreeBSD.org> From: underway@comcast.net (Gary W. Swearingen) Date: Wed, 20 Aug 2003 12:06:14 -0700 In-Reply-To: <20030820110031.6953360b.trhodes@FreeBSD.org> (Tom Rhodes's message of "Wed, 20 Aug 2003 11:00:31 -0400") Message-ID: <98k7986teh.798@mail.comcast.net> User-Agent: Gnus/5.1002 (Gnus v5.10.2) XEmacs/21.1 (Cuyahoga Valley, berkeley-unix) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii cc: FreeBSD-doc@FreeBSD.org Subject: Re: Kerberos in the 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: Wed, 20 Aug 2003 19:10:57 -0000 Tom Rhodes writes: > Greetings, > > I'm pondering the following question: > > What exactly do we do with the kerberos information in the handbook? > I have a Kerberos5 document which is nearly complete, should it: > > o Be a new chapter? > o Be added as a second part to the current KerberosIV information? > o Should I place it in the Security chapter, move the current section > to KerberosIV, add a note that Kerberos5 is only in FreeBSD 5.1 and > beyond? > > I'm leaning toward the last option but would like a few general > comments first. All of the Kerberos info should be in one sub-chapter (eg, 10.6) with "Kerberos" in the title. If krb4 is used by very few people, then it should be relegated to an article, with a note to that effect in the sub-chapter's intro. Otherwise, there should be two sub-sub-chapters (eg, 10.6.1 and .2), with the one that's expected to have the most readers comming first. (Unless krb4 is more popular only in 4.x in which case it probably should come first in keeping with the current 4.x vs. 5.x documenting style of the handbook, in which 5.x is covered by side-notes, etc.) If you expect more than a few people to need krb4 info, don't force them to mind-meld the krb5 info with "4/5 diff" info, unless the diff is really trivial or very well done. IMO, the handbook should concentrate on helping people with the software they are expected to want help with, and not use quality or availability of documentation as a means to try to influence their choice of software. It should even be careful about too much recommending and deprecating. Which reminds me of another pet peeve: the handbook often uses the weasel-words "not recommend", as in: We do not recommend modifying these values. instead of We recommend that you not modify these values. or We recommend that these values not be modified. It probably shouldn't even use "we": These values should not be modified, because [...].