@make(report)
@style(spacing 1)

@begin(titlepage)

@begin(titlebox)
Getting Started with...
How to Use...
First Steps to...
@end(titlebox)

Date
Revision number (if applicable)
System it's part of (if applicable)
Author(s)
Group it's from at MIT

@copyrightnotice(Massachusetts Institute of Technology)

@end(titlepage)

@comment<The Table of Contents Scribe produces should go here>


@chapter(Introduction)
What is the thing?
What is it good for?  Why should I care?
(Level of explanation should be very high, details later)

This manual will tell you how to...
Or, when you get to the end you will be able to...

It won't tell you how to...
For other information, see section on Documentation

Any special instructions about reading it

@chapter(Getting Ready or First You Need)

What's the ante to get started?
Any presuppositions, like
  we assume you have an account
  is your program only on one machine?  Which one?
  where to go to get an account
  do you have to be in a particular group?
  how can you tell if you are?
  minimum knowledge (e.g., Scribe, we assume you know a bit about
                           Unix and one editor)


Now the story starts.  On the whole, it's better to get them started
doing something immediately than to go into long discussions.

@chapter(Getting Started)

@section(Login)
First you must login.  Are you assuming they know some Unix?
Or are you undertaking to teach them things like login and
the DELETE key?
Any restrictions, such as you must use a VS100, or only color
graphics, and how do they tell?

Anyway, get them logged in.

@section(Preparations)
Any preparatory commands they must give, for example, making
a working subdirectory or defining something in their .login
file.  e.g, BLOX bgbsetup.

Explain, but not too much.

@section(Running Thing)
The command that invokes it.
To enter the <system>, type:
  
  example

Any cautions (like no blanks, any special words about the filename or
other parameters you want them to give)

You will see:
  
  example           show exactly what they'll see
                    
Explain the pieces of what they see.  Those that have significance,
anyway.  @description may help here.  But don't get too involved.

What if they don't see what you said?  Always anticipate common
problems and say what to do about them.

If this were a User Guide, we'd explain the complete command including
all its parameters here.

@chapter(How to Get Out of the System)
Always put this immediately here.  Say how to get out normally,
and how to get out in an emergency.

@chapter(How to Do the Most Common Thing--Usually, How to Make One)
This is where you can begin to explain how the program approaches
the problem.

E.g.:  RS1 is an electronic laboratory notebook.  Most experiments
       involve recording data points with respect to a variable
       (Example)  This is recorded as a 2-dimensional table of
       rows, columns, and values.  Example

       Therefore, the first thing we want to do is make a table.
      
Posit a hypothetical situation and give them working data.

Subcommand to enter
  show simplest case to invoke
  show and explain what they see
   (how to get out)
   (what if it didn't work)
  say what to respond to any prompt  Don't explain in detail
   unless it adds to the immediate issue.
  Do X
  You'll see X
  It means ...
  How to Undo it if mistake
       .
       .
       .  and so on

  when you're done, do ---- to leave

  What exists now?  Usually some object (file, table, etc.)
  What about it?  Will it be there forever?  How do I get
  rid of it?  Refer them forward to some maintenance section.


@chapter(How to Do the Next Logical Thing...)

E.g., RS/1, now we've got a table, here's how to graph it.

   Repeat sequence as in above chapter.

@chapter(Next Logical Thing to Do...)

and so on.

@chapter(Summary)
Reaffirm what you think they know, now.

@chapter(Maintenance of Objects)
  modify them
  see lists of them
  see contents of them
  delete them
  print them

@chapter(There's More)

@chapter(Documentation (for more information, see...))