Kerberos in the handbook

[Gary W. Swearingen]

Tom Rhodes <trhodes at 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 [...].