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.
Absolutely.
> 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
go.
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
Thanks,
Ardo
--
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: