[Show/Hide Right Column]

“Workshopping” Documents Through Technical Editors: An Important Function of Quality

David Dietz

How many times has this happened to you? You call up a particular large business, say, for example, your bank, and at some point—as you’re sifting your way through the numerous automated messages to get to just the right person to address your particular concern—you hear the following announcement: Your phone call may be recorded for quality assurance purposes.

Over the past couple decades, it seems like quality assurance (or QA) has become increasingly important to businesses around the world.

A fervent commitment to quality is easy to understand. With the seemingly unlimited choices available to vendors and consumers—not to mention the greater ease and frequency with which legal action is pursued—quite often the X factor that “seals the deal” for a sale (or opens the door for a lawsuit) is the quality of the company’s products and services.

You might think that this concern for quality would also extend to the documents a company produces. Well, you’d be half-right. While many businesses now employ their own internal QA staff, too often, skilled technical editors aren’t among those QA specialists—at least, not at first.

Many companies chug along for years thinking that those skilled enough to perform highly intricate and complicated work (such as structural or mechanical engineering)—and who are fluent in English—must surely be able to craft quality documents. After all, they’re the ones who know the product or service better than anyone else, right? Well … yes—and actually, that is part of the problem.

Workshopping Documents

A few years ago, I got a first-hand appreciation for how being a product’s creator can easily lure someone into believing that they are omnipotent and omnicompetent when it comes to that product. However, what a product’s creator may not realize at first is that this “ultimate knowledge and capability” is a double-edged sword. Because, while creators completely understand everything there is to know about the product, common human shortcomings can limit their ability to fully articulate it in any sort of medium—at least, not without a little expert guidance.

This lesson was brought home to me when I had the good fortune to write a play that a local theatre company was going to produce. For someone who’s been an aspiring playwright for many years, this was a pretty big deal, and I wanted to make sure that my script was in the best condition that it could possibly be for stage production. Now, perhaps you are asking: What does writing a play have to do with technical editing and/or QA? Well, believe it or not, all good plays go through their own kind of QA process, much like any other product, service, or technical document would.

In “the biz,” it’s known as “workshopping.”

Before a play ever sees full production on stage, it goes through a number of developmental steps. First, of course, the playwright imagines the story, setting, and characters. Then, the playwright writes a draft of the play’s script and puts it in the proper format for presentation. (Yes, even stage plays must conform to a very specific layout before any professional theatre company will even glance at it.)

Next, the play receives what is known as a “seated reading.” In a seated reading, a group of actors is cast in the various roles in the script and read the entire play aloud (including all stage directions, and sound and light cues) for the benefit of both the playwright and producers. And, if the playwright is particularly fortunate, other performers, playwrights, and production people—and even general theatregoers—will also attend the seated reading.

Because, at its heart, a play is such a visual medium, it’s more helpful to the playwright, the producers, and a general audience to actually see and hear it being performed, as opposed to simply reading the script. Once the reading is finished, all those present offer the playwright feedback, including positive and negative reactions, and suggestions for where the script could be improved.

Take it from me: A seated reading can be a singularly humbling experience. It opens your eyes to things that may not have occurred to you while you were writing the script, such as
  • inconsistencies in the story or characters (or both)
  • unintentional humor in the dialogue
  • physical components of the set and props that may be impractical for the theatre to create

But perhaps the most startling revelation I had during my first workshop experience is that sometimes the author knows details that are important to the overall script in his/her mind, but somehow, in the course of writing, he/she neglected to actually include those details in the script!

There is an old showbiz adage that one of the things an actor needs to be successful is a thick skin. Well, let me tell you, that holds doubly true for playwrights (take it from someone who’s both). If I had not gone through the QA process of workshopping, my ego would have continued to keep me blissfully unaware of both the serious—and not-so-serious—problems of my script. And thanks to the input I received from the various people who attended my reading, I was able to completely pull what was inside my head out into the open, put it on paper, and ultimately realize it on stage.

Had any one of those people—each one possessing a different but vitally important set of theatrical expertise—been left out of the mix, I’m convinced that my play would not have enjoyed the kind of technical and critical success that it did.

The Play (or Document) is the Thing!

If you think of a technical document as being like a play script, then the importance of having a process to workshop or review for it becomes academic. And, to their credit, many companies will now concede this point. But, even if they establish a document review process, too often it heavily relies on simple self-checking alone. This can cause major problems. Because, although self-checking is an undeniably important part of the document creation process, solely relying on it isolates the author and overlooks the double-edged sword of “omnipotence and omnicompetence.” And no one is immune to its effects.

For example, at the company where I work when I’m not writing plays (or acting in them)—engineers write almost all of the technical documents. And, of course, they’re experts at making sure all the components work together the way they’re supposed to in the overall product’s design. But, much like a playwright, their “omnipotence and omnicompetence” can keep them too close to their subject matter. Or, to put it another way, it becomes difficult to see the forest for the trees. Consequently, like any other author, they can inadvertently leave out important information. Furthermore, because they are so focused on the product’s technical aspects (for instance, making sure that tab ‘A’ does indeed go into slot ‘B’), they tend to gloss over other important editorial considerations.

In an effort to help rectify this situation, the management at my company compelled the engineers to delegate their editorial duties. At first, they passed those duties off to administrative assistants; perhaps because they assumed—as many people do—that being able to speak fluent English is the sole qualification necessary to edit a document. However, this assumption overlooks the subtle but important distinction between copy editing and content editing. And, while many administrative personnel are more than capable of copy editing a document—checking for things like grammar, spelling, and punctuation—content editing requires the capacity to understand the subject matter on a much deeper, technical level.

The Case for Technical Editors

While using the copy-editing approach may produce a grammatically acceptable document, without a technical editorial (content) review, its overall quality is unlikely to be improved. To put it another way, it’s like having a seated reading attended and performed by set designers and stagehands only. While they can certainly comment on the physical components of the play, they are unlikely to provide constructive feedback on things like character development or story arc. It’s just not their focus or area of expertise.

Mistakes that have occurred while using only a self-checking departmental technical review cycle range from:
The simple:
  • Using vocabulary and abbreviations that are meaningful only to the author or company
  • Stating the obvious: “Project-specific drawings are created specifically for each project.” (As if they would be created for anything else…)
To the embarrassing (and customer-enraging):
  • Using the wrong customer’s business name throughout a document
To the technically incorrect:
  • Inadvertently missing (or misplaced) decimal points in measurement tables that could have an impact on construction or safety
  • Inconsistencies in numbers, reflecting changing calculation results—(perhaps because an analysis had to be rerun with different parameters, but the needed changes weren’t made in all areas of the document)
  • Procedural steps that do not make sense when one tries to understand what is being asked (information may be missing—most likely due to “omnipotent” knowledge; or perhaps the text refers to an illustration that does not logically match the text, and adjustments should be made to one or the other or both)

Therefore, just as it is important to have the correct mix of theatrical professionals at a seated reading, it is important to include professional technical editors as part of the review (QA) process for technical documents. Technical editors help to “bridge the gap” between simple copy editing and more complicated technical content editing. Contrary to common misunderstanding, technical editors are not simply copy editors. They’re specialists in technical writing, a unique discipline that molds and shapes highly dense, jargon-ridden, technical content.

Technical editors use their combined technical and grammatical expertise to transform the document’s language and presentation order into a form that the document’s intended audience will more easily understand and accept. This includes helping to ensure that facts are consistent, explanations are clear, and that figures and tables are in the appropriate location and clearly convey the information they are supposed to convey. Most importantly, technical editors can help the author determine if there are any gaps in the information. This kind of detailed review improves each document’s overall quality and usability, thereby increasing its value to both customers and vendors.

For companies like mine, clear, concise, and correct technical documentation improves not only our bottom line, but also our reputation. Because no matter how impeccable the technical work may be, if it’s presented in a sloppy document, readers will question the accuracy of the technical information. This is a particularly important concern for my company because it operates in a heavily regulated industry: nuclear power generation. Our documents are scrutinized with a gem cutter’s precision by
  • utility personnel—engineers, managers, quality assurance personnel, and licensing personnel, among others
  • regulators—the Nuclear Regulatory Commission (NRC)
  • industry personnel in organizations such as the Institute of Nuclear Power Operations (INPO) and the Electric Power Research Institute (EPRI)

So, at my company, document mistakes can dissatisfy many different but equally important people. And complaints about document correctness and clarity (that is, quality) lead to internal corrective action processes for formal resolution, which cost both time and money.

For instance, a power plant may want to change the level of power it produces. Several different analyses must be run to determine the impact of the change, each using various operating parameters. Inconsistencies can occur when a number (or series of numbers) isn’t changed to reflect the results of the analysis for that set of parameters—a simple oversight easily made in tight deadlines… but one that a technical editor should detect. Why not the author? Remember that whole “omnipotence/omnicompetence” thing? It often tricks the brain into thinking it sees what should be there on the page (when, in fact, it’s not). A fresh set of eyes doing a thoroughly detailed review can ensure that the correct number is used.

Projects can get even more complicated (both technically and financially) when a regulatory agency like the NRC is involved. The project may consist of a proposed methodology that, if approved by the NRC, may save our utility customers hundreds of thousands of dollars once it is available to implement. But, if approval from the NRC is held up for any reason—including clarity or correctness within the documentation—so is the utility’s ability to use it.

A utility may also apply to amend its license so that it can increase (or “uprate”) the amount of power it generates and hire my company to perform and document the analyses necessary to make the uprate possible. Changes in plant equipment may need to be made. If incorrect data reaches customers, and customers don’t catch the mistake, they may begin making expensive physical changes based on that data. Furthermore, if incorrect data reaches the NRC, the time to provide clarification may result in delays to plant changes planned for already scheduled maintenance outages. Outages are incredibly expensive. Timing is critical, and delays can be extremely costly. Action based on one oversight or confusing information can cost companies, and many individuals, significant money and time.

So, if there’s an important lesson to be learned from my workshopping experience, it’s this: when it comes to any written material—whether it’s a script for a play or a technical document—as John Donne once famously penned, “No man is an island.” It takes contributions from many qualified individuals to successfully produce any sort of product or literature. And, when it comes to producing quality technical documents, it’s a good idea to include technical editors as part of your QA process.

(By the way, in case you were wondering… yes, I even “workshopped” this article through technical content editors before I even submitted it for publication! Thanks, Donna, Jennifer, and Anitha!)


Page last modified on Friday, March 12, 2010 01:54:08am EST
The content on this page is licensed under the terms of the Copyright.
Comments powered by Disqus
Not a member?
Join the SIG and STC!
Get the latest news!
Sign up for our announcements:


Support STC & our SIG
[toggle]

STC receives a small royalty for each purchase made through this portal.

STC buyers' guide

Stay in touch with the SIG with our community toolbar.

Looking for a web host? As an affiliate, we receive credit for new accounts made through this link:
Hosted By
Affiliate link

Corrigo
Corrigo: The newsletter of the STC Technical Editing SIG

Rate this article:
This article also appears in the following collections:
Category: Skills



Alert Also available as a blog...