Re: problems with docs in ascii format

Subject: Re: problems with docs in ascii format
From: Marguerite Krupp <mkrupp -at- WORLD -dot- STD -dot- COM>
Date: Sat, 4 Feb 1995 11:51:33 +0001

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


Previous by Author: Macintosh help authoring tool
Next by Author: Re: STC Info, please
Previous by Thread: problems with docs in ascii format
Next by Thread: Re: problems with docs in ascii format


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads