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:"John P. Brinegar" <johnbri -dot- primenet -dot- com -at- BUBBA -dot- UCC -dot- OKSTATE -dot- EDU> Date:Thu, 25 May 1995 08:18:06 -0700
Danna McLaughlin wrote:
> . . . we sometimes end up with several related procedures that use
> different words to explain the same task.
What a great way to totally confuse users. This is one of the most common
faults in technical documentation, and there is hardly any organization
anywhere that is not guilty of this crime including mine.
> 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?
Nope! Not OK. Some users will have no difficulty and others will be
completely stumpped.
> Has anyone out there dealt with these issues?
Yes, with considerable diffilculty.
> Has anyone developed a set of standards from scratch? If so, how did
> you go about it?
No, not from scratch. What we did do was establish a standards team to
represent all info developers. The standards evolved over time and the
standards manual was updated and grew fairly frequently. When the team
couldn't reach consensus on a standard, the decision was kicked up to
management.
> Should this be a democratic event, or should one person lay down the
> law?
If it is not perceived as reflecting the skills and preferences of the
people who will use it, compliance with the standard will be almost
impossible to assure.
A publishing product that can do a very good job of standards policing is
Frame Technology's FrameBuilder. FB is available for Mac, PCs with
Windows, and Unix stations. Editors can also verify compliance, but this
requires very good interpersonal relations.
> How much leeway should an individual writer have when it comes to
> wording?
Except in situations where a standard applies, as much leeway as he or she
needs. As to technical terms and product names, no leeway at all.
--
John P. Brinegar, Phoenix, Arizona, U.S.A.
Consulting and development
-Performance Support Systems
-Technical Communication
Phoenix Chapter, Society for Technical Communication
