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:Style Guide Help (thanks-and pretty long) From:chasity mcwilliams <chas -at- fcs -dot- uga -dot- edu> To:TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 29 Jun 2000 12:40:00 -0600
I want to say thank you to all of the people who responded
to my request for help. I was asked by a several people to
post the results of my query back to the list. Before I
do that, I would like to explain my situation a little bit
more. As I said in my previous post, I have never been
trained as a technical writer. I am a complete newbie and
I don't consider myself to be an actual technical writer
(meaning I've never held that title and it would not
occur to me to bill myself as one). I have been placed in a
situation where I am creating many help guides and manuals
as well as handouts or "cheat sheets". Most of these
things are software related. Others are processes for
accomplishing certain tasks with different pieces of
equipment. The reason that I rely so heavily on this list
is there are no writers of any kind in this particular
college (Family and Consumer Sciences at the University of
Georgia). I appreciate having somewhere to go that will
allow me to do this part of my job well. This entire spiel
is to warn everyone out there that I will probably post
many newbie or just plain dumb questions. I want to
apologize for that in advance. I take instruction fairly
well so just tell me if I need to take the question
somewhere else and I will with no hard feelings. That
said, thank you again to everyone who responded to my
request for help. On to the results.
Creating a Style Guide
1. Find out as much as you can about why the guide needs to
be created. That means questioning, reading through
previous documentation, and researching any standards that
are already in place.
2. Define a set of references. This step seemed to be the
most important step to many of you. The top suggestions
for references were.
a.Any Standards that are currently in Place.
b. Read Me First: A Style Guide for the Computer
Industry (Sun Tech Communications)
c. Microsoft Manual of Stule (Microsoft)
d. Handbook of Technical Writing by Brusaw, Alred
Most of the recommendations were that I get both the
Microsoft and Read Me First as compliments to each other.
3. Define the types of documents you will be creating. In
my case it will (mainly) be user help guides to the
specialized and commonly used software on our Lab
Computers. This step includes defining whether or not the
documents are going to be for print or web or both.
4. Work with Other writers to come to a consensus of what
needs to be included and what can be left out. This is
only if you are in a department with other writers or will
be working with a team. This one did not apply in my
case, but I do plan to run the first few drafts past the
technicians just in case they can add anything I forgot.
5. Define Document formatting. Formatting includes: page
sizes, margins, tabs, numbering, bullets, and fonts
(stlyes, types, and sizes).
6. Define Guidelines for screen captures and tables which
a. How the screen captures will be taken.
b. Image resolution and size
c. Caption formatting and placement
7. Define wording. Particularly:
a. Headings (imperative, declarative or gerunds?)
b. Dealing with the passive voice and conditional
c. Define wording for commonly used terms,
conditions, and situations.
8. Set standards for capitalization, punctuation, and
If I left anything out, just let me know. Thanks again for
all of the help. You will hear from me again. That's the
only thing I am absolutely certain about.
"You're not dying, you just can't think of anything
good to do."
chas -at- fcs -dot- uga -dot- edu