Re: Writing Conventions

Subject: Re: Writing Conventions
From: Stuart Burnfield <slb -at- FS -dot- COM -dot- AU>
Date: Wed, 1 Nov 1995 16:06:28 +0800

Jennifer Chiki asked what conventions she should use to denote directories,
scripts and attributes.

Geoff Bradbury had some good advice about what to do in the absence of an
existing convention, finishing "Whatever convention you settle on make
sure you document it at the front of your publication."

All I can add to this is 'first find out whether there is an existing
convention.' In your case there does appear to be a set of conventions
followed by many (though not all) UNIX vendors.

Does the software you're documenting run on a particular flavour of UNIX?
If so, follow the conventions in the system manuals. If it will run on
several UNIXes, I suggest you use the 'standard', which appears to be:

plain monospace: names of commands, directories, screen output
(e.g. Courier)

bold monospace: what the user types -- "To delete foobar, enter
*rm -i foobar*

italic: placeholders for things to be inserted by the user --
"To delete a file, use the rm command folowed by the
nbame of the file:

rm _filename_

I got these from a Sun Solaris manual.

Stuart Burnfield (slb -at- fs -dot- com -dot- au) Voice: +61 9 328 8288
Functional Software Fax: +61 9 328 8616
PO Box 192
Leederville, Western Australia, 6903

Previous by Author: [no subject]
Next by Author: Re: Commas (was: But for however)
Previous by Thread: (Fwd) Re: Keyboard vs. mouse
Next by Thread: Re: Using Word for autogenerated cross refs

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

Sponsored Ads