Creating an Admin Handbook
Marc Fonvieille
blackend at freebsd.org
Tue Jul 20 14:08:06 UTC 2004
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
More information about the freebsd-doc
mailing list