Monthly Archives: March 2010

Technical Stylist’s Tip: The Diagramless Diagram

Kathy Underwood

You know the kind of paragraph that seems to resist all your attempts at editing? Its sentences are usually filled with noun stacks (filled with abstract nouns), pronouns without clear antecedents, and passive voice—not to mention multiple independent and dependent clauses. You just want to write “awk” in the margin and move on, right?
The problem, of course, is that “awk” says no more than “This sentence makes me unhappy.” So what can you do to help both yourself and your writer to untangle a big sentence mess?
Over the years, I’ve adapted a technique to create a “diagramless sentence diagram” to help analyze problem sentences. Because sentence diagramming is not widely taught any more, I wanted to provide a visual representation of the sentence structure that could be used by writers who had no diagramming experience.

Let’s try this bit of bureaucratic reportage, which bears all the signs of a first draft:

Following a series of well-attended information sessions concerning the new multi-user features as well as other enhancements, user group members were invited to review and evaluate a project plan for the new users’ Web site to be established during a public forum sponsored by the Steering Team last Friday. However, the Steering Team was disappointed when only 2 of the 50 users were in attendance and because no questions were presented to the expert team assembled for the occasion.

“Awk” doesn’t begin to describe the problems in this paragraph. So let’s try to find something substantive by first identifying actors and actions as represented by the subjects and verbs.

sentence 1

  • actor user group members
  • action were invited to review and evaluate

sentence 2

  • actor the Steering Team
  • action was disappointed

At this point, we know that there are some users who’ve lost interest in whatever it is that the Steering Team is doing and that the Steering Team is disappointed. And if they all talk like these sentences are written, we know why. So let’s see what else we can dig out from those sentences.

sentence 1

  • actor the Steering Team
  • action were invited to review and evaluate
  • when “Following a series of . . . sessions . . . concerning . . . features”
  • why “to review and evaluate the project plan”

sentence 2

  • actor the Steering Team
  • action was disappointed
  • when “when only 2 . . . were in attendance”
  • why “because no questions were presented”

This far into the analysis, we should be seeing something meatier. What are we missing? The subject of the meeting—the actual topic about which there’s a lot of apathy, disappointment, and, one infers, smoldering resentment.

Note that as you identify additional key bits of content, your idea about the meaning of the text may shift significantly. Not infrequently, you’ll find that a writer will have buried a significant detail in a dependent clause or at the end of a prepositional chain. Also note that you might find that the explicit topic might be incidental to the real point of the sentence. It’s highly likely in such cases that you will need to query your writer.

So here’s a quick fix, admittedly done without the writer’s response to your carefully worded query and with a rash number of assumptions:

After the sessions on the new product release, the Steering Team invited user group members to ask questions and offer comments to an expert panel. The panel’s report will serve as the basis for services on the new product Web site.

The little set of labels (actor, action, when, and why) won’t rewrite the sentence for you. But they can at least help you tease out important details that seem trivial, thus enabling you to realize whether the writer might have hidden the real topic in the least significant parts of the structure.

I would like to add that this primitive analytical tool I’m using pales in its utility next to the real thing—sentence diagramming. For those of you who weren’t fortunate to be exposed to diagramming in school (and even if you were), I recommend Kitty Burns Florey’s Sister Bernadette’s Dog Barking: The Quirky History and Lost Art of Diagramming Sentences.

Do Your Magic!

Charles R. Crawley

By title at the avionics company where I work, I am a technical writer, but by function I am really a technical editor. And the engineers at my company often see me as a magician. They bring documents to me and ask me to do my magic on them.

Based on a posting on our Wiki, “Understanding the Value of a Technical Editor”, I would like to point out a few indicators about our worth and magical appeal.

First, my company is getting its money’s worth. I don’t know how the economic recession is affecting you, but it’s about to make my hands fall off. In less than half a year, the other technical writer and I have produced almost as many pages as we did IN THE ENTIRE LAST YEAR (emphasis added). Working harder (albeit, smarter) seems to be our alternative to hiring another writer.

Second, we are the masters of the documentation system that controls our documents. While I never intended to be a database administrator, it is in fact what I have become. We understand and control (to a certain extent) the review cycle better than anyone else. Engineers and managers always come to us to find out where something is “stuck.”

Third, we provide a level of quality control that is easily lost when non-writers take over the process. Inevitably, we fight over control of the Word documents (source files) and insist that engineers review Adobe Acrobat files, which are copies of the Word files. Whenever we lose control of this process, documents invariably get messed up in one way (writing) or another (formatting).

While I am thankful to still have a job, I am not happy with the amount of work we do because it has lead to a loss of focus on the actual writing. But I know that we contribute to the financial bottom line of our company. And I know that without our documents, equipment will not get certified, planes will not fly, and people will be even more unhappy with the airline system than they already are.

Also see, Understanding the Value of a Technical Editor(external link).

Bette Frick’s Marketing Bingo

Carol Lamarche

Bette Frick’s upbeat webinar, “Marketing Bingo,” was the first Technical Editing SIG quarterly membership meeting of 2010. In her engaging presentation, Frick, the Text Doctor®, presented 25 marketing strategies that every editor can use.

The strategies ranged from passive to active techniques. Key points included:

  • the relationship between trust and branding
  • marketing as a process
  • the importance of investing in marketing
  • old and new traditions in networking

The webinar presentation was based on a bingo game. A bingo card, consisting of 25 squares representing different marketing tactics, was supplied. Webinar participants (marketing bingo players) who scored “bingo” were eligible for a prize.

The downloadable “Marketing Bingo” handout, including bingo card and accompanying notes, is currently stored in the SIG archives at http://www.stc-techedit.org/file20(external link). An audio file for this presentation will not be available.

To review the “Marketing Bingo” presentation, download the handout and see the interview with Frick below.

How is branding a “trust mark,” or how is branding related to trust?
I am almost addicted to my brands. I’ve had three Saturns (unfortunately, GM killed that brand recently). My first Saturn was so good to me, I just kept coming back for more. I’ve had this Saturn for 5 years and have never had one single repair in that time. I probably would have driven Saturns until I went into the nursing home!

I’m the same way with my HP products. I have two HP printers and an HP laptop, and I just bought a brand-new HP laptop. I trust the performance and the support.

In the same way, we independents can establish our brand. Think about what you like in the brands you are attracted to and purchase. For me, it’s not about being flashy—just the opposite. I like dependability, a good price, surprising features that I didn’t know I needed or wanted, and good support. We can provide all that to our clients. Dependability means quick turnaround of documents when possible and always a quick response to e-mail. I price my editing and my training classes fairly (not at the high end). There’s always someone less expensive and always someone who’s more expensive, but there’s never someone better! And so on … All businesses have a brand. I want to make sure mine is a positive one.

You talk about the “new business cards,” such as Web sites, social media, blogs, podcasts, and webcasts.
a) How important are these to editors?
I think these can be as important as you want them to be. For me, my blog is a great opportunity to prewrite my newsletter articles with an audience in mind; it’s different than writing in my journal. The webcasts are a way to highlight my teaching skills. For others, Twitter, Facebook, and other venues may suit their style and their businesses well.
b) Can we make it in business without these?
Sure, you can make it in business without any of the marketing tactics that I suggest. I simply couldn’t or wouldn’t give up my LinkedIn. It is too productive for me in uncovering leads into companies where I want to find work.
c) For people who aren’t familiar with producing or marketing with these, where would you suggest we start?
As a trainer, I believe the key to better performance is always—you guessed it—TRAINING! Take a local or online class about any type of marketing that you don’t understand. You’ll find it’s not so mysterious, and you’ll come away with a list of action items to make that particular method work for you.

Could you say a few words about Point 4, “Listings on others’ sites”? (It’s not explained in the notes.)
The only problem with listings on others’ sites is that if you complete the listing and sit back, waiting for the phone to ring, you’ll be disappointed. Do your best to create an attractive, persuasive, dynamic listing, and don’t count on ever getting a response. Then, when you do, BINGO! I found my book designer for my Marketing Bingo book, Greg Field, on a listserve for Boulder Writers’ Alliance (I posted a small ad). Just last week, Greg asked me to provide a reference for someone who found him through his Rocky Mountain Publisher’s Guild listing. I provided a glowing reference (Greg’s wonderful); he got the job; BINGO! He’s gotten two jobs through me through networking and listings.

Since I’m itching to get into the ground with my organic garden (and snow is predicted for this week), I’ll liken listings to gardens. You won’t get produce unless you plant seeds. A listing on someone else’s site or in a book of freelancers is a seed. You may get something green from it, but not every seed produces growth. (Not to mix metaphors, but if you went fishing without bait, you wouldn’t catch many fish, would you?) Enough with the metaphors.

In Point 23, “Be elected to leadership,” you mention that we should be careful to strategically select the organizations that we serve. What are the marks of a good fit?
It would be smart to lead a group of your peers (editors, perhaps). It surely will enhance your credibility if you succeed. It would be even smarter to provide leadership for an organization where your clients hang out. I volunteer for the Boulder Area Human Resources Association because HR managers, directors, and vice presidents appear at the meetings—and it’s those people who hire trainers.

You mentioned that editors and other technical communicators who are on a payroll often don’t think about how to get credibility or publicity, and are often the first fired during cutbacks. How can we market ourselves within our organizations?
You can use every one of the 25 Marketing Bingo tactics! You can write blogs for your organization; you can then turn the blog posts into newsletter articles. You can volunteer to work on the company Web site. You can organize, sponsor, or underwrite events. You can work at your company trade show. You can be elected to lead groups within your company’s industry. It’s all good—and it will gain you credibility and good publicity. You’ll build a brand of being the “go-to” person; you’re the one who really knows what’s happening and who’s who; you’re indispensable. Then sit back and watch your career blossom.

You plan to publish your Marketing Bingo concept in a book soon. What will readers find? Why should we stay tuned?
Yes, the book is in process. I’m on the third draft, and graphic artist Greg Field is working on the design. Readers will learn more about how each Marketing Bingo tactic might work for them, and they’ll learn tips for implementing each tactic in their own business. They’ll find links to other sites for further information and tips on each tactic as well.

For me, the good news is that I have so much business this spring (through careful Marketing Bingo promotion) that I don’t really have time to devote to the book right now. This is not a bad problem to have!

Although the webinar has passed, may people who use your marketing bingo card still contact you for a free gift?
Sure, if they tell me they made “bingo” by being willing to use a tactic or actually doing it … if they get five tactics in a row, they get bingo!

“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!)