ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ SUGGESTED GUIDELINES FOR THE FORMATTING OF ON-DISK DOCUMENTATION: ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

1.  Documentation files should be one of two types--either straight,
unformatted ASCII text or, if you need to control pagination, with ASCII
12 formfeed symbols for page breaks.  This is the only print formatting
command that you should use.

2.  If you paginate, allow for a maximum of 58 lines per page.

3.  Double-check the number of lines on each page.  Remember that the line
that the page-break symbol is on counts as the first line of the new page.

4.  Put your page breaks at the left margin, where they're easy to spot,
with nothing else on the line.  If you put them at the end of a line, that
line counts as both the last line of the previous page AND the first line
of the next page.  This can throw your count off if you're not careful.

5.  Leave at least one blank line at the top of each page, in addition to
the line that the page break symbol is on.  This will help to take care of
situations where skip-perf is turned off or where the top-of-form isn't
set properly.

6.  Some users like to adapt the on-disk documentation into on-line help
files.  Make it as easy as possible for them to do this without having to
either waste disk space or do a lot of editing to your file.  Set your
text flush left and ragged (uneven) right, rather than justified.

7.  Your documents should be pleasing to the eye and functional, but for
the same reason as stated in #7, don't be over-generous with margins,
indents, lines between paragraphs and items, or white space in general.
Paper costs money and printouts take up file space.

8.  If your document is lengthy and you're using formfeeds, put them at
the beginning and end of your document as well as at your page breaks.  A
formfeed at the beginning may save the user from wasting paper if they've
done a print-screen and forgotten to do a formfeed before printing your
file. Likewise, a formfeed at the end may save them grief later on if
their printing program doesn't automatically issue a formfeed at the end
of a document.

9.  Many programs have several text files--a manual, a readme file, and a
whatsnew file, for example.  Format each one the same way.  If you use
formfeeds in the manual, for example, use them in the others as well.

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ADDITIONAL SUGGESTIONS: ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

1.  Avoid the potential conflict that can occur with generic file names
such as README, READ.ME, and the like.  If you're uncompressing more than
one "file collection" at a time (I didn't want to use "archive"), and the
text files are all going into the same directory, this can cause problems.
Stick with README (or README1, README2, etc.) as the filename but use an
extension that is likely to be unique--perhaps the first three letters of
the filename of your main program.

2.  Include a FEATURES file with the same extension as your README file,
if any.  This file should include a concise but comprehensive summary of
your program's main features, its hardware and software requirements, a
revision history with the most-recent revision first, and nothing more.

Here's the reason for this suggestion:  Many bulletin boards have a file
view feature which enables users to peek inside a file collection and read
text files on-line, helping them to decide whether or not to download a
particular program.  This feature is very useful, but unlike viewing a
file with LIST, for example, you can't skip around.  Putting the revision
history at the end of the main documentation file, for example, means that
you have to wade through the entire document just to find out how version
X.97 differs from version X.96.

If a person has to search several files--particularly a long manual
file--for the information that they need, this can take up so much time
that it's faster and cheaper to download the entire program instead,
particularly if the connect time is costing them money.   They then have
to waste more time searching for the information after they've downloaded
the program, often finding that they have no need for it.

Putting enough information in a brief FEATURES file to help a person
quickly decide whether or not they want the program or need the upgrade
will not only make it easier for the people who can use your program to
find and identify it, but will also help the sysops when they screen the
original upload.

3.  Include a DESCRIBE.EXT file with two items.  The first should be a
one-line, 40-character description that people can use when uploading your
program to other boards.  This will help to insure both accuracy and
consistency.  The second should be a three-line description, 40 characters
per line, for use on those boards which support multi-line descriptions.

--Bob Simanski          June 8, 1989