Re: another user manual chapter
On 11 Dec 1997, Ardo van Rangelrooij wrote:
>
> 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
>
You're right - this could get messy. What about this: perhaps we should
take your suggestion to merge the Files and Basic Commands chapters a
little further, and mix the initial chapters up a little more, that is,
merge the overview and documentation chapters in with the files and basic
commands stuff. Or rather, categorize them differently, since we don't
want one enormous chapter.
I'm thinking of this as "Part 1" of the manual. Part 1 would cover the
general user interface of the system, stuff everyone will have to know, no
matter what they want to do with Debian. This includes simple text
editing, using bash, the basic files stuff, and basic commands. It's hard
to separate these things because it's hard to do *anything* with Linux
until you know this stuff.
I think the way out of the mutual dependencies is a tutorial-style
approach for Part 1, as opposed to a topic-centered one. Imagine a long
login session, where the reader tries out a whole lot of things, learning
concepts along the way.
A possible outline (just to clarify what I mean, not really well planned):
0. Introduction: what's in the manual, political commentary, copyright,
etc.
1. Boot your newly installed system.
2. Log on as yourself, not root. Why logging on is needed (multiuser
system). What's the difference between normal users and root.
How to shutdown, in case they want to shut down before the end of the
manual. :)
3. When you log on, you see the shell prompt. Virtual consoles.
X vs. Console mode. How to get a shell prompt if you have X working.
The rest of Part 1 assumes you're at a shell prompt. How to log out.
4. Typing commands. Command, options, and arguments. How commands are
described in man pages. more, less, info, and reading simple
documentation. These documentation commands are used to introduce
commands in general: "man man"
5. Files and directories: what are they. _Very_ basic file operations.
Also explore some of the files already on the system.
6. Creating your own files: a simple text editor tutorial. Use the easiest
editor, or maybe vi since it's small fast and standard.
7. The shell. Basic job control. Stdin, stdout, and redirection.
Just uses bash since that's the default. What's an environment
variable. Seeing what variables are set, setting variables to customize
things.
8. Customizing the shell with .bash_profile. Discusses hidden dotfiles
and ls -a. Also introduces new text editing tricks and concepts as the
shell config files are edited.
Login shell vs. non-login shell, and which files are used for each.
9. Permissions. More on root vs. normal users, discussion of groups.
How to maintain your privacy.
10. Dealing with disks: removable media, editing fstab. Serves as concrete
application of text editing and permissions, building further on those
concepts.
11. Intro to X. The X environment: server, clients, window manager. X
resources. Displays, etc. Assumes X is already installed.
Tutorial on customizing the window manager or something, using an X-based
editor. Differences between X and Windows/Mac. .xsession[-errors]
12. Basic commands. Other "essential" commands not yet covered. gzip, tar,
grep, tail, maybe some common shell builtins.
13. Simple shell scripting. Automating repetitive activities. Nothing too
difficult. Perhaps use a discussion of boot scripts as an example?
14. dpkg: how to add and remove software, see what package a file is in.
How to submit a bug report, how to ask questions on debian-user.
So that's more or less Part 1. It's all mutually interdependent, and
covers all the basic concepts you need to interact with the system. It
gives a general tour of all the aspects of the system. It flows naturally
from less to more complicated aspects of the system, rather than hopping
between topics.
Part 2 is more modular: It's split like the current user manual outline.
Idea is that people can read Part 2 in whatever order they want, or use it
as a reference, or browse as it interests them. So the chapters aren't
interdependent.
We'd have a chapter on misc/advanced files topics, misc/advanced commands,
misc/advanced X ("misc" means "not essential enough to be in Part 1, but
likely to be useful to non-advanced users"). Common tasks like making
backups would be covered. Chapter on networking (ppp, telnet, ping; but
not sysadmin-ish stuff like traceroute). Chapter on preparing documents
and text processing. We'd have an overview of different shells and text
editors. Etc. - pretty much what's already in the second half of the
user manual outline.
Disadvantages:
Part 1 would be less modular, so perhaps harder to distribute tasks. On
the other hand it'd be more integrated, which is good for the reader.
Discussion of a single topic would be spread around, so a good index would
be vital. The "reference" aspect of the manual would be deemphasized;
however, man pages serve that purpose, no?
> 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.
>
I think it makes sense to mix the Shell chapter in with Basic Commands and
Files, since it's really all interdependent; then you more or less have
what I've suggested above, if Advanced Commands becomes Part 2. Plus we
get to leave the horrors of tcsh for Part 2 :)
> 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
>
Basically what I'm suggesting is like this, only Advanced Commands is
moved to Part 2, and Basic Commands, Shell Commands, and Text Editing are
interleaved so that they can be more comprehensive without forward
cross-references. Also, advanced aspects of Shells and Text Editing are
moved to Part 2. 1,2,3 are still first, except the more complex aspects of
Documentation are moved to Part 2, and some parts of Overview could be
moved forward so they make more sense (e.g. processes goes after
discussion of some commands and the shell).
> If this sounds reasonable, Havoc and Oliver could team up for the
> basic commands chapter.
>
I'm open to that.
If we do it the way I'm suggesting, perhaps we could have a small team for
Part 1? We'd have to develop a good detailed outline, and then we could
do some cut and paste from what we've already written, and then everyone
grabs some of the remaining bits to fill in.
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: