Style guides: where to begin?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

John Balchunas reports: <<I have been tasked with developing a style guide
for our operator manuals... I have not worked with style guides up until
now, and am currently interested in how I should best approach this task, as
well as the general scope of a style guide.>>

The best approach? Don't reinvent the wheel. Pick any good style guide that
suits you (e.g., Sun's "Read me first"), then spend a few moments looking
through it to find out aspects of your particular work that it doesn't
cover. Document those in a small, short, well-indexed guide, and begin that
guide with the following statement: "With the exception of the points in
this guide, use "Read me first" for all other points of style." (Specify
your favorite dictionary too just to be sure everyone's using the same
definitions.

<<Generally speaking, how large of a document are style guides?>>

They can be huge and comprehensive (e.g., Chicago Manual of Style = nearly
1000 pages) or short and sweet (the FERIC style guide is ca. 32 pages). In
short, I took my own advice. The longer it is, the less likely people are to
read it, so focus on the really important points:

<<What is the scope? What topics need to be addressed in order for a style
guide to properly function?>>

Only the topics that writers really need to know. Ask your colleagues what
questions they are constantly seeking advice on, and ask your editors what
problems they're constantly wasting their time correcting, and prioritize
those topics.

<<What Frame specific information needs to be included?>>

None of them. Create a single, clean template, and provide a brief
explanation of how to use it correctly. Works much better than digging
through a style guide to find out information that already exists in the
template. For more details on this and other tips, see: Hart, G.J. 2000. The
style guide is dead: long live the dynamic style guide! Intercom,
March:12-17.

<<The company that bought us has a style guide (in French)...>>

Then in addition to what I've said, make sure you sit down with
representatives of their writers and editors to develop a single guide that
works for all of you. You're going to have to impose some kind of
consistency on the writing of the merged companies, and there's no time like
the present to get started. Particularly since each group of writers and
editors has probably come up with clever solutions for problems the other
group is still grappling with...

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"In seeking wisdom, the first step is silence, the second listening, the
third remembering, the fourth practicing, the fifth -- teaching
others."--Ibn Gabirol, poet and philosopher (c. 1022-1058)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

TECH*COMM 2001 Conference, July 15-18 in Washington, DC
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.