[3655] in Athena Bugs
help
daemon@ATHENA.MIT.EDU (Malcolm X CasSelle)
Wed Nov 15 17:06:42 1989
To: bugs@ATHENA.MIT.EDU
Cc: cprivate@ATHENA.MIT.EDU
Date: Wed, 15 Nov 89 12:42:33 EST
From: Malcolm X CasSelle <mwcassel@ATHENA.MIT.EDU>
The On-Line help seems to have an error in the Scribe section
explanation of text. In addition, the explaination doesn't seem too
intuitive. The On-Line help section is #2 Specific Document Types,
under Scribe formatting, #4 Text, #2 A Simple Sample Paper (.mss). The
text looks like:
A Simple Paper (Sample .mss file)
To format a paper, double-spaced with indented paragraphs, you would
include the following at the beginning of your manuscript file:
You type:
@device(device)
@make(type)
@style(spacing 2, indent 5, spread 0, leftmargin 0.7 inches)
The @@device command indicates the type of printer that
produces the formatted text. It defaults to @@device(lptln).
The @@make(type) command tells Scribe the document type. If
this line is not there, Scribe assumes the simplest document type,
``text''. The spread parameter tells Scribe how many extra lines
to leave in between paragraphs.
To see the results, look at the sample .PS paper module.
First, the @device default is now Postscript, and the line doesn't even
have to be included. Also, the explanation should make it more clear
that 'device' isn't a valid device, something like this might do the
trick:
You type:
@device(Postscript)
@make(text)
@style(spacing 2, indent 5, spread 0, leftmargin 0.7 inches)
The @@device command indicates the type of printer that
produces the formatted text. Here we've specified 'Postscript,'
which is the most commonly used device type. If it is not there
Scribe assumes the a Postscript device.
The @@make(text) command tells Scribe the document type. If
this line is not there, Scribe assumes the simplest document type,
``text''. The spread parameter tells Scribe how many extra lines
to leave in between paragraphs.
To see the results, look at the sample .PS paper module.
****
Obviously the .PS sample would have to be changed. However, the line
"You type:" is kind of deceiving if you don't put valid arguments in the
@device and @make commands.
This problem though is indicative of others I've found in a lot of
documentation, which is that the docs aren't tested thoroughly on
new-users. Many things experienced users may find very intuitive aren't
necessarily so for new users. I've had a number of users (including
Professors) come into the office and ask how you get the screen to
scroll once it gets filled up. Well naturally, you press space bar. I
thought that all MOREing said:
[Press space to continue, 'q' to quit.]
but apparently that's based on the setting of an environmental variable
for MORE. This is just a simple example, other more devastating ones
including overlapping windows. I think a good thing for users would be
a quick reference page for new users including:
* most basic emacs commands
* window key-click combinations (to iconify,
normalize, hide, unhide, etc.)
* emacs & (the ramifications of backgrounding)
* xterm & (let new users know they can have olc in one window
and try it out in another)
* logout -- it's important to make sure logout in complete
Better than just getting started, this one page piece of documentation
could also be posted in clusters, relieving frustrated users trying to
do simple things when olc's tied up or the office isn't open.
However, this idea is only secondary to testing out documentation on
users. Testing is the guts of software development. It only makes
sense that documentation development needs testing too.
Malcolm CasSelle
Athena Consultant
mwcassel@athena.mit.edu
