Creating a style guide?

Subject: Creating a style guide?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 14 Apr 2005 10:24:31 -0400

Martin Bosworth reports: <<I've discovered that the developers' documentation is generally solid and easy to understand, but it's rife with grammatical errors and inconsistent style usage...>>

Count yourself lucky that the biggest problems are simple ones. With some of my ESL authors, I grapple daily with stuff that sometimes borders on the incomprehensible, whatever other minor problems it may have. Don't forget to compliment your authors on the things that they're doing right.

<<The primary app developers do not speak English as a first language, so they often miss contextual cues and best standards, such as using "he/she" constantly as opposed to "they", or avoiding gender-neutral language altogether. I've been pondering whether or not I should create a style guide for the department to refer to, both to improve their skills and free me up to concentrate on more creative projects.>>

A style guide is rarely useful for anyone other than an editor and some professional writers. In my experience, just about nobody ever consults such a guide or follows it well on those rare occasions when they do consult it. Moreover, referring authors to a style guide rather than working with them to understand and fix their problems undermines the key to a successful author-editor relationship: the "relationship" part.

I spend a lot of time answering questions posed by my authors, and it pays off enormously well: they understand that I'm always willing to drop what I'm doing and help them solve their problems, and over time, they've come to rely on me and have become eager to work with me. This removes many of the frictions in the author-editor relationship and makes it a true collaborative endeavor. That also makes it a much more efficient process.

Rather than creating a style guide, you may find it more productive to schedule a weekly lunch meeting where you informally teach them a specific point of grammar, while also using the opportunity to socialize. It can be very effective to keep tabs on the kinds of problems each individual has, and make time (10 minutes will usually do it) to discuss specific problems (one at a time) with the authors and help them figure out how to solve the problem. Concentrate on the things that are costing both of you the most time, because demonstrating a quick payback on this investment of time clearly demonstrates your value to the author, while also repaying your time investment.

<<Is it the right course of action to take, and if it is, what're some good suggestions or resources I can use in its creation?>>

Style guides can be useful for those who use them. <g> That being the case, you want to find out two things: what your authors want to see in a style guide, and how they want to access the guide. If you design the guide to follow their preferences, they'll be more likely to use it; if you make it easily accessible, they're less likely to find a reason not to use it. (You could consider this exercise one of finding an answer to the following overall question: What could I do to encourage you to use our style guide?)

For example, I created a style guide for a former employer in consultation with a half dozen authors, and used their recommendations to ensure that the content, style, and format were appropriate for their needs. I then added a hyperlink to the intranet version of the guide directly at the top of our main Word templates, so a single click took them right to the guide--thereby eliminating the "I couldn't remember where it was on the intranet" and "it takes too long to scroll through my bookmarks" excuses.

The guide still didn't get used all that often, but that's a fact of life with nonprofessional (and some professional) authors.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


Creating a Style Guide: From: Martin Bosworth

Previous by Author: What is wrong with this sentence?
Next by Author: What should one do with split infinitives?
Previous by Thread: Creating a Style Guide
Next by Thread: Re: Creating a style guide?

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

Sponsored Ads