user's manual

[robert havoc pennington <rhpennin@midway.uchicago.edu>]

Hi,

 I've just started working on a section of the user's manual on files
(basic file operations, the organization of files on the system, etc.) 
and have some questions, etc. This section is intended to go near the
beginning, after an explanation of logging on and the difference between
root and normal users, but doesn't assume knowledge of using the shell.

1. Comments are of course welcome! I've put the sgml at:
  http://student-www.uchicago.edu/users/rhpennin/file-management.sgml

2. I'm finding it natural to write in a sort of tutorial style. I
sort of alternated conceptual explanations with "try it out" sections. 
I'm thinking of the manual as the kind of thing one might sit down with
and read in front of the computer while trying things out, rather than as
a reference manual (man pages work for that, right?) - is this
appropriate? Also, is there or should there be a standard format for "try
it out" sections? I used:

<enumlist> 
<item> <tt> command to type </tt> 
<p> explanation of what happened and why 
<item> ...
</enumlist>

But I don't even know what this ends up looking like, it's just
what I typed in for now.

3. To be able to read straight through the manual as a tutorial, it has to
be planned so that the same things aren't explained twice, and so the
reader has the appropriate background at each stage. What's the plan for
coordinating all the chapters? Should we discuss what's in each one and
what order they're in on this list?

Apologies if I'm asking things that have already been covered, I'm new to
this...

Thanks,
Havoc Pennington




--
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 .