TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
Regards
---
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
