robert havoc pennington <[EMAIL PROTECTED]> 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: [EMAIL PROTECTED], [EMAIL PROTECTED] 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 [EMAIL PROTECTED] . Trouble? e-mail to [EMAIL PROTECTED] .
