Date: Wed, 20 Aug 2003 12:06:14 -0700 From: underway@comcast.net (Gary W. Swearingen) To: Tom Rhodes <trhodes@FreeBSD.org> Cc: FreeBSD-doc@FreeBSD.org Subject: Re: Kerberos in the handbook Message-ID: <98k7986teh.798@mail.comcast.net> In-Reply-To: <20030820110031.6953360b.trhodes@FreeBSD.org> (Tom Rhodes's message of "Wed, 20 Aug 2003 11:00:31 -0400") References: <20030820110031.6953360b.trhodes@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Tom Rhodes <trhodes@FreeBSD.org> 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 [...].
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?98k7986teh.798>