[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: scope of user manual (was Re: another user manual chapter)

robert havoc pennington <rhpennin@midway.uchicago.edu> writes:

> 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) 

As mentioned in my reply to your other email I'm all in favour of the
changes you propose. 

> 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. 

Excellent insight!

> 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. :)

All this makes perfectly sense to me.  This puts the user's manual in
a whole new light.  As mentioned I think this is definitely the way to

Looking back at how the various manuals came about it's kinda funny
how things went: Initially we only had the user's manual, although the
sysadmin's manual was already mentioned.  When I started looking at
things I proposed to actually have the latter manual.  Now we're
putting stuff back from the latter into the former, albeit less
detailed.  At the time I also proposed the netadmin's manual and I
already have a feeling we'll probably be putting network stuff in the
sysadmin's manual, albeit again less detailed. 

> Anyway, I'll write later about my chapter and its place in the user
> manual.
> Thanks,
>  Havoc



Ardo van Rangelrooij
home email: ardo.van.rangelrooij@tip.nl, ardo@debian.org
home page:  http://www.tip.nl/users/ardo.van.rangelrooij
PGP fp:     3B 1F 21 72 00 5C 3A 73  7F 72 DF D9 90 78 47 F9

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: