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.

Where Does Only Belong?

Michelle Corbin

The Boston Globe publishes a blog called “The Word Blog” where I discovered (via a Twitter post to this blog) an article(external link)* about the placement of the word “only” in a sentence. It was fun to see the journalistic view of this grammatical construct (or nit, in the author’s words). Where do you fall on where only belongs in a sentence? Is it more than a nit in technical communication?


* http://www.boston.com/bostonglobe/ideas/theword/2009/11/who_moved_her_o.html(external link)

The Technical Stylist Meets the Definite Article: What Bloody Man Is That?

Kathy Underwood

In Act I, Scene 2, of Macbeth, a blood-soaked sergeant enters the presence of King Duncan, which prompts the king to ask the obvious question:

“What bloody man is that? He can report,
As seemeth by his plight, of the revolt
The newest state.”

What is the answer to this kingly question? That’s a usage pundit reporting some change in language usage that seems likely to provoke controversy. And that’s me after one of those interminable style discussions that characterize editors’ meetings. I sometimes—well, often—feel that I’ve just left the battlefield and that I need to find the nearest medic. It’s not that we’re all contentious. (In fact, very often these discussions are more like rowdy, amusing party games.) It’s just that the topics we address are fraught with complexities that make the plot of the Scottish play look like Dick and Jane. Worse yet, we frequently struggle with questions that few if any customers would ever recognize as questions.

Take the definite article. Please. The editors at SAS continue to struggle with the question of which SAS product names require the definite article and which require the zero article (linguist-speak for no article at all).

How do you make such a decision in the absence of clear guidelines from the usual usage manuals that we consult (Chicago Manual of Style, Harper’s Dictionary of Modern American Usage, etc.)? In the interest of precision, we have to make choices not unlike those parodied in the show Beyond the Fringe(external link) in the 1960s. In a sketch entitled “Portrait from Memory,” Jonathan Miller as Bertrand Russell meets the philosopher G.E. Moore, who, as it happens, is holding a basket of apples on his knees. Russell asks Moore if there are any apples in a basket. Moore says no. Then Russell asks if there are some apples in the basket. Moore says no. Finally, Russell asks Moore if he has apples in the basket. “’Yes,’ he replied. And from that day forth we remained the very closest of friends.” (Can you imagine what Moore would have been like in editors’ meetings?)

For our in-house style guide, my worthy colleague and fellow editor, Joel Byrd, created an article on the use of the definite article with product names. He reified our department’s lengthy and ongoing collaborative discussions and e-mails and produced a very useful table as well as a field test to help us make the best choice. Here is my paraphrased version of the guidelines:

  • Use the definite article if the primary noun is countable (example: “the SAS Forecast Server”).
  • Use the definite article if there is general industry agreement that the primary noun requires a definite article (example: “the SAS Intelligence Platform”).
  • Use the zero article if the primary noun is uncountable (example: “SAS Business Intelligence”).
  • Use the zero article if the primary noun is a metaphor “that does not have a defined, commonly accepted meaning in the software industry” (example: “SAS Management Console”).

The test devised to assist the editor is as follows:

  • Write the primary noun in lowercase and then in uppercase (for example, “console” versus “Console” and “the console” versus “the Console”).
  • Does the name of the object in isolation mean the same thing as it means in the product name? If so, use the.

Based on several examples of SAS product and component names, I decided to create a list of our extant primary nouns so that we could have an at-a-glance guide for new product names and whether or not they should take the definite article.

  • Use the definite article with these primary nouns:
    • platform
    • portal
    • provider
    • server
    • software
  • Use the zero article with these primary nouns:
    • analytics
    • console
    • intelligence
    • studio

This list should be satisfyingly clear. But consider the problem with console. Our basic rules say that if the primary noun is uncountable, we should use the zero article. But the word console is obviously countable. On the other hand, in the land of product names and software products, console is a metaphor and not countable. Very crazy-making. So every time I come across a product name with the word console in it, my editing hand wants to insert the definite article.

There’s an even bigger problem. With any usage guideline, there’s a “missing middle” (one or more ungrounded assumptions) in the syllogism. That is, when and how do we decide that a given agreement has reached a critical point that forces us to change our guidelines? Yes, you guessed it: We have to have another editors’ meeting.

Why is it that grammar and usage rules, which once mastered should provide comfort and confidence, can be so frustrating? Why are there so many exceptions to cope with? And why do all those usage pundits have so many different opinions and remarkably little consensus? I think that those questions are answered succinctly by Otto Jespersen in his introduction to The Philosophy of Grammar (found in the first sentence of Chapter 1):

“The essence of language is human activity—activity on the part of one individual to make himself understood by another, and activity on the part of that other to understand what was in the mind of the first.”

Even if we think of the effects on language of just a few of the more dramatic forms of human activity—revolutions, inventions, and catastrophes—we quickly realize that language is a quivering, changeful thing. From vowel shifts, to spelling, to syntax, language always reflects the psyche of any given group. (And which psyche is more shifting than that in the software industry? A new product or technology can completely change perspective.) That’s especially true when society is in flux. It’s that shared, shifting psyche that dictates what really happens with language. And we might argue that the shifting is where the sublime arises.

As editors, we often have to make many decisions that we know will ultimately prove ill-advised, if not completely wrong, and that any number of our fellow editors will find objectionable. But that’s what human activity, war, peace, and the dialogue of the psyche are all about.

Think of the changes from “on line” to “on-line” to “online” that have occurred over the past few decades. There was no legislation, there was no vote, and there was no universal epiphany. So why did “on line” and “on-line” drop out of use (mostly—they are still used in some settings)? In The Fight for English, the linguistic historian David Crystal says that the short answer to questions about disdained usage is “somebody thought it was wrong.” (See Crystal, page 110. Crystal’s book, by the way, is a very readable history of grammar practice and grammarians over the past few hundred years.)

All editors, and especially those of us who serve on in-house style teams, have to make arbitrary decisions all the time. We must be as autocratic as is essential to produce a cohesive body of documentation. But we can never lose sight of the world outside our doors. We have to listen to that bleeding sergeant even if we don’t want to or haven’t got the time to hear what he has to say.

Obsessed with Possessives

Andrea Wenger

We see it everywhere: our schools, our places of business, even in notes stuck on our refrigerator. Yes, my friends, I’m talking about apostrophe abuse. The Obama administration, faced with two wars and an economy teetering on the edge of disaster, is unlikely to make this a priority. So it’s our duty as professional communicators to stamp it out.

My elementary school teacher made it sound easy. “To make a word a possessive, add an ’s, unless the word is a plural ending in s, and then, just add an apostrophe.” Ah, life was simpler in elementary school. True, many atrocities (such as Grammar Girl’s report of a menu advertising Ladie’s Night) could be avoided if people applied that straightforward rule. Yet there are myriad exceptions, and even the U.S. Supreme Court can’t agree on them (more on that later).

Pronouns

Possessive pronouns don’t use apostrophes: hers, his, its, ours, theirs, whose, yours. Most of us wouldn’t have a problem with this rule if it weren’t for the contractions it’s (it is, it has) and who’s (who is, who has). The sentence, Who’s book is this? doesn’t look wrong to me, but of course, it is. It should read, Whose book is this?

Personal possessive pronouns are often called absolute possessives, because they can occur with no noun following them. For example, a sentence could read It’s her book, or The book is hers. Absolute possessives are sometimes used mistakenly in conjunction with other possessives. For example, She worried about hers and his safety, should read, She worried about her and his safety. A better choice, though, would be to recast the sentence: She worried about her safety and his, or She worried about his safety, and her own.

Singular Words Ending in S

If a singular word ends in s, is it correct to add an s after the apostrophe in the possessive form? That depends on who you ask. It’s a matter of style, not grammar. As a technical writer, however, I consider it a usability issue. When people read, they hear the words in their head. So where the style guides disagree, I use pronunciation as the ultimate arbiter.

According to The Chicago Manual of Style, if an s at the end of a singular word is pronounced, the possessive is formed by adding ’s. The same is true for words ending in x or z: boss’s office, Alex’s wallet. However, if the ’s would be awkward, avoid the possessive and use of instead: the governor of Texas, the history of jazz. If the s, x, or z is not pronounced, the s after the apostrophe may be omitted: Illinois’ capital, Margaux’ necklace. Follow this practice only if you’re certain of the pronunciation.

Fowler’s Modern English Usage recommends omitting the s after the apostrophe with names ending in an iz sound, as in Beau Bridges’ brother.

The Associated Press Stylebook omits the s after the apostrophe altogether in singular words ending in s. Since newspapers are pressed for space, I suppose they can be forgiven (although I’m not sure I’ll be forgiven for that pun). But unless you’re required to follow AP, I recommend including the s for consistency with pronunciation.

Ancient Names

Ancient names can be troublesome, in part because style guides also disagree here. According to Fowler’s, ancient names ending in s form the possessive with an apostrophe alone: Achilles’ heel, Moses’ journey. However, according to Chicago, while names ending in an eez sound receive only an apostrophe, others use ’s: Aristophanes’ plays, Zeus’s wife. When in doubt, or when both ways look wrong, Chicago recommends using of, as in son of Isis or teachings of Jesus.

Multiple Possessors

Is it Joe and Renalda’s fishing poles, or Joe’s and Renalda’s fishing poles? That depends. Are the fishing poles joint property, or do Joe and Renalda each have their own pole? Placing an ’s only at the end of the group of names denotes joint ownership. Placing an ’s at the end of each individual name denotes individual ownership.

Attributive Forms

The distinction between an attributive form and a possessive is often unclear. A users’ manual isn’t a manual belonging to users; it’s a manual for users. Nevertheless, Chicago recommends retaining the apostrophe except in the case of proper names: citizens’ advocate, Panthers game, Boys and Girls Clubs of America.

Genitives

Analogous to possessives, genitives that denote value or time use an apostrophe, as in five dollars’ worth or two weeks’ notice. The apostrophe in this case stands in for the word of.

Double Possessives

In this idiom, also called a double genitive, a possessive noun or pronoun is used after of, to denote one example of several:
An associate of Sheila’s (or an associate of hers)
A collection of Bob’s (or a collection of his)

According to Garner’s Modern American Usage, some people dislike this idiom, but it has a long history and is widely approved. It can also be intrinsic to meaning: it wouldn’t make much sense to say a collection of Bob. Nevertheless, it might be better to recast the phrase as one of Bob’s collections.

Using an Apostrophe to Form a Plural

The practice of using an apostrophe to form the plural of abbreviations or numerals has fallen out of favor. The most common usage is to simply add an s: UFOs, the 1940s.

With lowercase letters, an apostrophe is needed for clarity. This is usually unnecessary with uppercase letters, but the apostrophe may be used where confusion might otherwise ensue, as in A’s, I’s, and U’s.

”Mind your p’s and q’s.
He got A’s and B’s on his report card.”
but…
He got Bs and Cs on his report card.

Chicago offers several examples of when to use the apostrophe to form a plural and when to leave it out:

maybe’s
ifs, ands, or buts
yesses and noes (or yes’s and no’s, especially if used with maybe’s)
dos and don’ts

For special cases like these, it’s best to consult a good style guide. But if you’re forced to rely on your own judgment, don’t obsess over it. When it comes to apostrophe use, intelligent people can disagree. Jonathan Starble(external link) wrote in Legal Times about a rift in the 2006 Supreme Court case Kansas v. Marsh: in the majority opinion, Justice Thomas consistently used Kansas’ statute, while in the minority opinion, Justice Souter used Kansas’s statute. Although I consider myself a political moderate, I have to side with Justice Souter on this one.

Reprinted with permission from the Carolina Communique(external link), the newsletter for the Carolina Chapter(external link).

More Than Grammar: Expectations of Technical Editing New Hires

Shelley Thomas

As an academic who teaches technical editing to undergraduates, I wanted to know what employers’ expectations are for their new hires. In September, I asked the discussion list: “What would you expect from a new hire who has completed a technical editing course (beyond being well-versed in grammar, mechanics, and punctuation)?”

I received 18 responses to my question, and the range of issues raised by the listserv participants surprised me. While some of the responses stressed knowledge of the basics (strong knowledge of grammar, punctuation, and style guides), other responses were less focused on editing mechanics, concentrating instead on adept interpersonal skills and familiarity with various technologies. The technical editor’s responsibilities extend beyond grammar checking; the editor must be able to ensure consistency, logical structure, completeness, usability, and effective communication among all parties.

Grammar and Mechanics

While any company should be able to safely assume that a new technical editor would have a solid command of grammar, punctuation, usage, and mechanics, this is not always the case. Several respondents emphasized that this basic knowledge, which I assumed applicants would possess, was lacking. One respondent, Candy Jenkins, said, “I don’t believe enough emphasis is stressed on grammar and mechanics in institutions of higher learning, so having a good foundation in that is important.” Many companies use editing tests to ensure that their applicants have this most basic editing knowledge.

Style Guide

New editors must be familiar with standard proofreading marks and be experienced with using more than one style guide, especially the more widely used guides such as APA, Chicago, and AP. Because editors are divided regarding the use of soft copy and hard copy edits (see “Paper, Screen, or Scissors? Editing on Hard Copy or Soft Copy,” Corrigo, July 2007), editors continue to use proofreading symbols and authors rely on a standardization of these symbols to understand the edits. With the knowledge of various style guides comes an ability to create and maintain an in-house style guide (or a document-specific style sheet) to promote consistency. Furthermore, new editors must acquaint themselves with whatever style guide the company uses. Virginia Janzig remarked, “The editor needs to find out what style guide is used and then use it even if the editor doesn’t agree with some of the guidelines.” This knowledge allows the editor to edit with confidence by referencing a standard to support edits and make only necessary changes.

Interpersonal Skills

Editors must be able to adeptly defend their edits across many levels of an organization’s hierarchy. Their edits must be based on sound reasoning (or a notation in a style guide) and readability (as defined by the user or audience). To do this successfully, a new editor must make intelligent edits, write helpful and respectful queries, and persuasively communicate the changes to the author(s). These skills allow the editor to assist the author and to advocate for the user without projecting an “I-just-got-my-degree-and-know-it-all” attitude. When a new editor explains her edits to an author, she must do so with tact. And, according to Jennifer Coury, “[Editors] should always be able to gracefully explain [their] edits (either by e-mail or on in person).” Not only should effective editors be able to write clear queries within the document, they should also be able to discuss the emendations with the author through e-mail, in person, or on the phone.

Teamwork

While many technical writers and editors wish they could work alone, it just isn’t so. “Gone are the days when the editor sits alone in a corner, rarely to be approached except in times of grammar crises,” wrote Catherine Rudiger. New editors, especially, must integrate themselves into whatever project, big or small, they need to accomplish. This element requires, as Stephanie Weiss explains, “teamwork, flexibility, follow-through, and project management skills.” All too often, junior employees defer to their more senior colleagues. A successful technical editor, regardless of rank, must communicate clearly to writers of all skill levels and not be intimidated by a person’s degree or seniority. Good communication allows consistent editing of documents across organizational lines and document versions.

Documentation consistency requires an editor to look beyond sentence-level edits to examine page design, template use, layout, and font. With this editing task, a new hire must refer to a style guide or documentation guidelines to maintain the organization’s “look and feel” for documents, whether delivered in e-versions or in hard copy.

Technology

New hires must be familiar with various technologies: Web, content management systems (CMSs), advanced features of word processing, XML/DITA, and FrameMaker, to name only a few. As Jim Purcell wrote, “Nothing irritates writers more than editors who know language but have no idea about technology.” A familiarity with technology allows a new hire to acclimate quickly to a new position without extensive (and expensive) training. With the job market growing ever tighter, new employees in technical writing and editing must demonstrate complex skill sets. This includes, as Christina Bottomley emphasized, “the ability to upload docs to a website, learn a CMS, follow a style guide, and update changes in multiple docs.” An interest in technology helps new hires investigate editing options and delivery methods. It also and keeps them on the cutting edge of software packages.

Translation

In the global economy, technical writers and editors must prepare for their documents to be translated into other languages. With this in mind, an editor must be able to “meet the challenges of creating documents that will be translated” and understand “strategies for keeping translation costs low,” according to Julie Kumasaka. This editing skill involves an eye for consistency in usage and terminology, avoidance of jargon and idioms, and clarity of expression. In addition, a new editor may have to justify these types of edits to an author persuasively and confidently. Furthermore, knowledge of another language aids in the task of translation and deepens an editor’s understanding of English usage.

Conclusion

As I have researched undergraduate technical editing courses across the country, I have found that many address the issues expressed in this discussion This discussion opened my eyes to the complex nature of technical editing and created an avenue for more effective instruction. The editor is ultimately responsible for ensuring the author’s message seamlessly reaches its audience. At times, educators become removed from the work world, and we (educators) need to update our skill set and corporate knowledge. From the detailed comments I received, educators cannot take anything for granted when it comes to preparing undergraduates for “the real world.”