Re: problems with docs in ascii format

[Marguerite Krupp <mkrupp -at- WORLD -dot- STD -dot- COM>]

On Mon, 30 Jan 1995, Tamara Miller, Computer Documentation Specialist wrote:

>> I've been struggling with how to present commands in the ascii version of the
> documentation. I've checked several other university gopher sites for ideas,
> but none that I've found use a consistent method: some use both all-caps and
> double quotes in the same document. All-caps wouldn't be bad, but it
> won't work for our Unix docs, because Unix commands are case sensitive. I'm
> also concerned that no matter how many notation keys I include, if I use
> quotes, people will think that they are part of the command. As I'm working, I
> am trying to separate the commands on separate lines - is that enough?

> Has anyone else dealt with a similar situation? Any suggestion?

Tamara, The situation you describe is a lot like doing UNIX manpages. My
experience has been that people who use them are a lot more interested in
content than format, and that they try to use online searching (rather
than visual scanning) to help them find the information.

That being said, there ARE a few tricks you can use to enhance the visual
aspects of the communication.  Remember that you're not limited here by
the page format.  Use a header line, in italic if you like, to indicate
what follows; for example:

SYNTAX:

mumble[abc|def|ghi]

where:
        abc = choice 1
        def = choice 2
...and so on. You can use tabs, underscores (on a separate line) or
whatever, to make it easire for your reader.  Examples are a big help in
this format, since people can just copy them electronically and use them
in their code.

For more ideas, see O'Reilly's Nutshell series on UNIX. It's not my
favorite operating system, by a long shot, but since it exists, someone
has to document the programs that run under it, and that's where we can
make a difference.

Good luck with your rorject.

Marguerite