Creating an Admin Handbook

[Marc Fonvieille]

On Tue, Jul 20, 2004 at 08:43:38AM -0400, Ken Smith wrote:
> 
> One last wimper, then I'll shut up - it's really not worth an argument. :-)
> 
> IMHO then you're not really interested in a definition of user vs admin
> task (which is fine).  You're interested in clumping things more people
> are likely to need in the first volume (which is fine).
> 
> I think what we really need to answer is who we expect Joe Average
> Handbook Reader to be.  If it's a typical-ish home user then your
> approach definitely makes sense - clump "the first things that people
> need to know" together and this sort of person is by definition both
> user and admin so this isn't horrible.  If it's a more corporate or
> otherwise large-site audience this isn't necessarily the best split.
> If I received a box with media and two books in it for a new OS we
> were thinking about using I'd grab the admin guide on the way out
> the door for the day planning to do a little evening reading and I'd
> be annoyed if it didn't include the Install docs.  I'd also be scared
> that "they" expect normal users to install the OS and applications,
> one of my reasons for considering this OS is getting away from an
> environment where users can easily dammage the system...  :-)
>

>From some points of view everything could be in admin part and
everything (or quite) could be in user part.  It's just a problem of
vision of things.  It's an endless talk.

I did not give my opinion about the split, let's fix that :)

I don't really like the split idea, why?  Well cause of something I'd
call "the FAQ syndrome".  Our FAQ answers to 90% of questions you can
read on -questions, newsgroups, and other mailing lists, but quite no
one read it.  It'd even be interesting to compare Web trafic for both
of Handbook and FAQ.
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.

For the moment
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
gives an "overview" of Handbook sections/chapters, if after the split(s)
the Handbook keeps a similar ToC it will be fine, otherwise we will
loose a part of the Handbook strengths.

Well this is "my personal opinion", and of course I see some advantages
in the split, it's why I did not say "No" to the split.  I say "Ok but be
careful" :)

Marc