Re: another user manual chapter
Hi,
robert havoc pennington <rhpennin@midway.uchicago.edu> writes:
> Hello,
>
> I've got a lot of the chapter on files and filesystems done; I'll have a
> lot of time to work on it in the next few days so I'd love comments. It's
> available in several formats at: http://pobox.com/~hp
Great!
> It overlaps a bit with the basic commands chapter; this makes sense to me
> if basic commands is a quick start/reference, perhaps before the files
> chapter, but doesn't make sense to me otherwise. In the latter case
> suggestions on what to put where would be helpful. For that matter, I'm
> not totally clear on the scope of the user manual vs. FAQ vs. sysadmin
> guide.
Well, things could even get more complicated since the shells chapter
is currently planned between the files chapter and the basic commands
chapter. This could get messy with quite some overlap and things in
the wrong order. The current order of the first few chapters is:
- introduction (standard intro stuff)
- overview (booting, logging in/out, shutting down, etc.;
concepts of users, shells, processes, etc.)
- documentation (man, info, dwww, /usr/doc/, etc.)
- files and file systems
- shells
- basics commands
- advanced commands
- text editing
with the first three chapters being ok w.r.t. order and contents.
Given what I've read in the files and basic commands chapters, I
think the fourth chapter should be the basic commands chapter merged
with the files "part" of the files chapter. The remaining "part" of
this latter chapter can be merged with the advanced commands chapter
(although nobody is working on that yet). A thorough discussion of
the file system hierarchy belongs in the sysadmin's manual, though
(see below).
This leaves what to do with the shells chapter. Its intended purpose
is to explain the different shells available, basic shell commands,
maybe even some shell programming (but of course not in (t)csh :-).
This can e.g. come between the basic and advanced commands chapters.
So, we would then get the following order:
1. Introduction
2. Overview
3. Documentation
4. Basic Commands
5. Shell Commands
6. Advanced Commands
7. Text Editing
If this sounds reasonable, Havoc and Oliver could team up for the
basic commands chapter.
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.
What do you think?
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: