Re: A Far Broader Question

Subject: Re: A Far Broader Question
From: "Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM>
Date: Mon, 10 Feb 1997 16:48:01 -0800

At 04:38 PM 2/10/97 -0500, Amy Brown wrote:
>What do folks include in their style guides, anyway? My style guide will
>pertain to printed documentation and online Help.
>

Your style guide should contain any and all information you think
is necessary to promote consistency within a writing team or across
product lines. Good candidates for categories include:

* Writing style: Voice, tense, tone, person, sentence and paragraph
length, using contractions, using jargon, etc.

* Nuts & bolts formatting and punctuation: capitalization, commas,
italics, boldface, table and figure captions, numbering styles, and
other stuff.

* Standard verbiage: Whether to use "select" or "choose", "click" or
"click on", "on line" or "on-line" or "online".

* Which templates to use for which documents.

* Which reference documents (commercial style manual, dictionary,
thesaurus) to use for what the style sheet doesn't cover.

* Guidelines for screenshots: Should data be real or made-up, what
color should the border be, and so forth.

Two very important points to keep in mind as you create a style guide are:

* By-in ensures adherance. Creating a style edict to be followed by all
team members is a recipe for disaster. Giving all team members a chance
to contribute will go a long way toward its successful adoption.

* The opportunity for change is a good thing. The style guide should be a
living document. What works this year may not work next year. Schedule
regular periods of review, both to keep the style guide in sync with
documentation trends (what was on-line last year may be online now)
and to afford input by new team members.

Sue Gallagher
sgallagher -at- expersoft -dot- com
-- The _Guide_ is definitive.
Reality is frequently inaccurate.

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html


Previous by Author: Re: Documentation Tracking and Version Control Software
Next by Author: Re: Platform of choice
Previous by Thread: Re: A Far Broader Question
Next by Thread: Re: A Far Broader Question


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

Sponsored Ads


Sponsored Ads