scope of user manual (was Re: another user manual chapter)
On 11 Dec 1997, Ardo van Rangelrooij wrote:
>
> Concerning the scope, as I wrote in another email the user's manual
> assumes a working system ready to be used. Installing and configuring
> software belongs (among other things) in the sysadmin's manual (except
> of course for what's in the various configuration files in the user's
> home directory which does belong in the user's manual). In other
> words, the user's manual is limited to the user's home directory part
> of the file system while using the rest of the file system, while the
> sysadmin's manual and netadmin's manual are about that rest of the file
> system. With the FAQ I assume you mean the "Short Guide to Using
> Linux". This can be sort of an abbreviated version of the chapters 2,
> 3, and 4 (and maybe 5?) of the user's manual.
>
This is what I've been thinking about the scope of the user manual -
perhaps it's too late to change, but for what it's worth. (I'll email
about the organization of the user manual later - limited time right now)
IMHO we should divide the manuals by who will read them rather than by
their content. i.e., we should think about the readers' present
knowledge, their desired knowledge (what they might be trying to
do with the software), and how our manual will get them there.
Possible readers:
1) user on a large system administered by someone else
2) user of a home system, dialup to internet, Debian used instead
of Windows or MacOS
3) administrator of a large system
etc. (?)
This means that there may be some overlap between manuals, which is a good
thing I think.
For example, reader type 2 will have to know a lot of sysadmin stuff, such
as how to set up a printer and what's in the file system outside of /home.
If this info is only in the sysadmin guide there are problems:
- the sysadmin guide has to be written for both naive home users and
experienced professionals; both groups might find the end result
distasteful
- the user has to keep flipping back and forth between the two manuals;
and we have to keep track of cross references between them
- the sysadmin guide has lots of stuff the user won't care about much,
but has to dig through to find what matters to them
It makes sense to me to merge readers 1) and 2) (home users and users on
large systems) into the user manual; general info about the system and how
it's organized outside of /home will be useful even to those who don't run
it themselves. This manual should be thorough and tutorial in flavor, the
idea being that after you install, if you sit down and read the user
manual in order, trying things out, you'll know how to get work done on
your computer and set up your computer to work the way you want. It
should also be a reference, covering a lot of oft-asked debian-user
questions.
Basically I'm saying that the user manual should contain a lot of the
things found in the sysadmin manual, perhaps explained on a more basic
level (and less comprehensively) and targeted to, well, users. It should
be standalone and not require the sysadmin guide.
This would fill a real void. A user is lost in a sea of man pages, not
knowing which ones to read, none of them giving background info, etc. Plus
a user manual really needs to be distribution-specific, so that all the
tutorials work "out of the box." To really be useful I think the user
manual should be fairly complete in itself, not yet another component of
the scattered and partial existing documentation.
Hope that makes sense - my two cents worth. :)
Anyway, I'll write later about my chapter and its place in the user
manual.
Thanks,
Havoc
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-doc-request@lists.debian.org .
Trouble? e-mail to templin@bucknell.edu .
Reply to: