Re: Writing Conventions

[Geoff Bradbury <bradg -at- INTEXT -dot- CPSG -dot- COM -dot- AU>]

At 18:07 30/10/95 EST, you wrote:
>  I am currently assisting in writing an Installation Guide, and have run
>  into some problems with writing conventions.  What conventions should I
>  use to denote the following types of information (information enclosed by
>  asterisks):

>  1. Directories / Subdirectories
>     Example:   " Expanding the tar file will create a subdirectory
>  *mcinstal*.

>  2. Script names
>     Example:    " Make sure that Oracle scripts *coraenv* and *oraenv*
>  were copied.

>  3. Attributes
>     Example:   "If this file does not exist, create it with owner *oracle*
>  and group *dba*.
__________________________________________________________
At 8:18 1/11/95 AEST, I wrote:

Greetings Jennifer...

Good to see the recent flamewars haven't scared all the students away!

There aren't any hard-and-fast rules about the conventions in which you're
interested. From my point, consistency is the priority. You could simply
italicize the relevant items. Or, you could italicize items 2 and 3, but
format item 1 in a contrasting face. Arial 10pt, for example (assuming your
body text is in something like Times 12pt). I'd steer clear of bolding,
underlining or excessive formats: they quickly clutter the page and break
your readers' flow.

Whatever convention you settle on make sure you document it at the front of
your publication. I always include a small section entitled "Conventions
used in this publication" in the Preface.

Hope this helps.
__________________________________________________
Geoff Bradbury - Technical Writer for InTEXT Systems
"Makers of extraordinarily fine text storage, retrieval, routing & analysis
software."

Come visit us at http://www.intext.com/

My writings reflect _my_ views.

"I love deadlines.  I like the whooshing sound they make as they fly by."
           - Douglas Adams