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: Documentation Standards? From:Susan Kloster <srk -at- PLAZA -dot- DS -dot- ADP -dot- COM> Date:Thu, 11 May 1995 05:55:56 -0700
> I'm trying to learn more about developing standards for a small
> documentation department (three writers). We put out hundreds of pages
> per month. We have worked for a while with unspoken standards, but we
> sometimes end up with several related procedures that use different
> words to explain the same task.
If you are writing to the same audience it's very important to use the same
standards, terms, and naming conventions. For instance, we write hardware
documentation and between the marketing dept. , the software goups, the
engineers and the support people some devices are referred to differently by
each. If we didn't decide on what we (the writers) are going to call a
device and be consistant, imagine the confusion.
> Is this breed of inconsistency confusing to the user, even if a very
> basic action is being described? For example, is it okay to tell
> someone to "enter the value onto Screen 35" in one set of instructions
> and then tell them to "type the value onto Screen 35" in another set?
Yes!! Use "enter" when the user must press the enter key after data is
typed, and type or press when you don't need to use the enter key. These
types of conventions are fairly standard
> Has anyone out there dealt with these issues?
> Has anyone developed a set of standards from scratch? If so, how did
> you go about it?
We formed a core group of writers to determine what standards should be
adhered to.
> Should this be a democratic event, or should one person lay down the
> law?
Democratic, this will help ensure that the standards are used.
> How much leeway should an individual writer have when it comes to
> wording?
Use common sense here..there are many ways to word a sentence. You You have
to assume a level of writing knowlwege. Writers should know how to use
bullets, but you should all use the same bullets (dots, checkmarks,
squares.....). A style guide is just that...a guide. Everyone has there
own style.
Include things like...
* Fonts
* Terminology
* Abbreviations
Also the purpose of the style guide is to provide guidelines so that all the
documentation from a department is consistent and effective. Is should
provide outlines for bulletins, newsletters, guides, online, etc.
Things like...
The style guide will really depend alot on what sort of documents you all
produce. You can't possibly cover everything in a style guide...there will
always be one offs...get the important stuff. Look at some examples..ie The
Chicago Manual of Stye.
Good Luck
---------------------------------------------------------------------------
Susan Kloster srk -at- plaza -dot- ds -dot- adp -dot- com
Technical Writer (503) 294-4200 ext 2299
ADP Dealer Services
---------------------------------------------------------------------------
