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

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,

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

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

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

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.


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.


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: