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: 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
