Creating a style guide?

Subject: Creating a style guide?
From: Kate Stout <stout -dot- k -at- comcast -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 15 Apr 2005 07:33:33 -0400

I like Geoff Hart's suggestion of setting up a regular lunch seminar to focus on one aspect of writing. Since you already have a friendly relationship with the developers this might be very well received. Two other things that were helpful for me in a similar situation: A cheat sheet and a template.

The cheat sheet is simple: a list of common problems, such as its/it's, their/they're - customize it to the things you are seeing the most. The cheat sheet should be one page at most. Send it via e-mail, but also print it and hand it around so people have it "right there" when they need it For example,

it's - Short for "it is"
its - Belonging to it (possessive)

If they don't already have a template for their work products, you can put one together that has the items that are commonly included. You can also give hints in the template to remind them how to used it. For example, if it were an API description, you might have something like this, where the notes in braces will be replaced by the writer

API Overview
[Two or three sentences about what this API accomplishes, and what important things the user needs to know.
Start with a verb, like Creates, Updates, Deletes, Searches.
For example "Creates a new employee entry, and generates an employee id. The employee entry has only the employee name and ID. Use UpdateEmployee to add the rest of the employee data"]

[List any important constraints. Try to state the constraint positively. For example
"Use only if the connection has already been created."
"Don't use if the connection has not yet been created."]

Detailed description
[Describe any relationships between the parameters in the API. Describe likely uses. You do not need to describe internal system workings, such as how the database will be updated. Any possible exceptions should be described in the exception section below. Keep it in the present tense.
For example:
"CreateEmployee takes two required strings, employee first_name and last_name, and creates an entry in the Employee database. The return value is a string that is a unique id generated by the system, which is used to identify the employee."]


I found that while people still struggled, using a template helped a lot, because it reminded them what they were supposed to say, and how they were supposed to say it. I got a lot of "parroting" of the examples, but at least things were more consistent, if occasionally a bit more stilted.

Kate Stout

Writing and Editing Services
Making It Clear


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.

Previous by Author: Re: What notebook did you buy?
Next by Author: RE: Client Complaint
Previous by Thread: What should one do with split infinitives?
Next by Thread: Re: Pattern language for tech writing

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

Sponsored Ads