Re: another user manual chapter
Hi!
Sorry for the somewhat late reply. I was kinda busy this weekend.
I nevertheless had some time to think about what you're proposing in
this and your other email. I also wasn't feeling that comfortable
about the current setup and the interdependencies of the first few
chapters. Your proposal is an excellent way out of this "mess" and I
think we should go for it.
I further propose to split the user's manual into a separate tutorial
(your "Part 1") and a separate reference guide (your "Part 2"). This
way the former can stay more or less stable while we can easy add
chapters to the latter, or even split it up in dedicated parts, one
for programming, one for document preparation and text processing,
etc. Further, when e.g. GNU Hurd is "Debianized" we could have a
tutorial for it ready without having to write one from scratch, while
the reference guide could be used without needing much adaptation at
first.
This also should make it feasible to have the tutorial ready when
Debian 2.0 is released which will be early next year. I certainly
don't intent to push us to have it ready at all cost, but it's a goal
worthwhile striving for, I think.
All in all, I see advantages all over the place :-).
I also like your idea of having a small team writing the tutorial,
since you're right is all kinda interrelated and somewhat difficult to
split up in clearly defined pieces.
So, unless someone has objections we should start working on this as
soon as possible.
Thanks,
Ardo
robert havoc pennington <rhpennin@midway.uchicago.edu> writes:
> 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
>
--
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: