STC Tech Valley Chapter

Creating a style guide minitially seem like a terminology affair ("option button" or "radio button" - pick one), but the real challenge lies in persuading the department to adopt new style principles. Some writers will feel threatened by change, and respond in bizarre and unpredictable ways. Whisper campaigns and ambushes may lie in wait for you. Beware, innovative editor! Before you even think about the literary details of style, prepare to do battle with the true Goliaths and Grendyls: the department itself. By following these five rules below, you can avoid an unexpected apocalypse when you reveal the new guide.

The Five Rules

Rule #1: Don't exclude people from decisions that affect them. This seems like common sense, but it's almost impossible to achieve. Try getting 12 writers to reach consensus about a controversial matter of style. You might spend 45 minutes discussing whether to call something a screen or window, and still never agree.

While too many cooks in the kitchen spoils the broth, letting one or two do all the work results in half the diners complaining vociferously about the broth. You'll have to make a tradeoff between efficiency and political appeasement. You want to let everyone have a say; however, doing so leads to chaotic and endless discussions. The trick is to make everyone feel included, even if they aren't ultimately making the decisions.

Try these ideas:

• Create a shared web site on your intranet to ask for feedback and initiate discussion
• Stop by cubes and ask for opinions
• Listen carefully and take notes
• Clarify ambiguity when it occurs and paraphrase responses to ensure understanding

Keeping your co-workers involved means keeping your efforts alive. They're less likely to reject something to which they've contributed.

Rule #2: Don't introduce new styles without good reasons. A style guide is often a collection of rules that have no firm basis in logic (unlike deciding whether to end sentences with periods). You're often merely choosing descriptors, such as whether to call squares of a dialog box "areas," "boxes," or "sections."

If there's no overwhelming reason to adopt a new convention, you're better off leaving the guide as is. New rules mean more work, and unless you're the boss, your co-workers will resent the imposition -- that is, unless you have good reasons. That a rule is decreed in the Microsoft Manual of Style is not enough to win your coworkers' hearts. In fact, it's the easiest way to create antagonism for it.

Rule #3: Don't expect any thank-you's for your hard work. You most likely have put hours into the preparation of your style guide, looking through many other style guides, drafting, editing, collecting comments, and redrafting. You may have sacrificed lunch hours, stayed late at work, or worked from home. Maybe you sacrificed a trip to Disneyland just to work on the style guide. The result? A well-polished work of art.

Don't expect anyone to be grateful for it. What you see as art is perceived by others as merely additional work. Your thick style guide is something they'll have to digest, apply, and then be corrected for misapplying. No, make no mistake about it: this style guide means trouble, and you've laid it at their door. Expect spite and resentment.

Rule #4: Anticipate not only objections, but extended, relentless wars against what you thought were inconsequential points of style. Inevitably there will be some entries in your style guide that seem inconsequential to you (for example, not introducing a table with a colon, or choosing the term "option button" rather than "radio button"). Be warned that one man's style trinket is another man's grammar treasure. A handful of your fellow writers see life in a different light and will inform you of that in no uncertain terms. When dealing with these minor issues, be prepared to make concessions. It's better to break a grammar rule than shatter relationships with your co-workers.

Rule #5: Listen closely when others express concerns. Don't make the mistake of returning belligerence with bellicosity. Clarify the reasons for objections, paraphrase to communicate your understanding, and be willing to bite your tongue and concede. One technical writer, Thomas Barker, says his ability to listen to others is what helped him advance his career. Says Barker, "If there were a single thing that advanced my career more than any other, it was learning how to listen to people carefully and respond in a way that lets them know I value their opinions." Failing to listen is a boomerang. If you don't listen to others, they won't listen to you. So listen up!

Conclusion

As you define your style guide, be sure to plan for the social impact of the new rules. We often drown ourselves in grammar minutae, obsess over stylistic consistency, or slavishly follow the Chicago Manual of Style, but these literary matters are not the biggest obstacles in creating a style guide. The biggest obstacle is how each of your teammates responds to change. Take these rules as a roadmap to dealing with their concerns and you can create and implement a style guide that everyone does not resent.

Tom H. Johnson writes online help and how-to guides for a large financial firm in St. Petersburg, Florida. He is also the webmaster for the STC-Suncoast chapter, which is based in the Tampa Bay area, and he does  freelance writing.

Four steps to a Killer resume!
By Dwain Celistan

A key tool in the process of securing another opportunity is via a resume. As an executive recruiter, we typically receive hundreds of resumes per week. There are over three million resumes on the larger internet sites. Thus, it is important to breakthrough the “clutter” to communicate your capabilities to the reader/potential hiring authority.

The first element of the strong resume is to state your objective. This will help the reader know your employment desires. Defining your desires is also energizing and challenging.

The objective section will set the stage for the balance of your resume. The balance of the resume should reinforce through your experiences and education your ability to meet/exceed the requirements of the type of role(s) outlined in the objective.

Your work experience is the next most important component. For each role you should provide two components, responsibilities and accomplishments. Responsibilities are essentially items that are similar to a job description. They are the requirements for someone who has had that position. By contrast, accomplishments are the quantitative things you’ve done while in the position. The weighting should skew most heavily to accomplishments with an 80/20 weight.

Second, compose a concise two to three line statement of your major responsibilities. For each position, focus on the larger aspects of the role in an appealing manner to the reader. Stay with the highlights versus details. Remember, the hiring authorities are probably familiar with the responsibilities of your role. For example, a Director of Sales knows the content of a territory sales reps role. Similarly, a Plant Manager knows the core responsibilities of a line foreman or maintenance engineer.

Third, and arguably the most important component of your resume, the accomplishments you’ve had while in each role. Accomplishments are quantifiable benefits you delivered or led, such as, generated X revenues, reduced Y costs, efficiencies were improved Z percent, secured Y more clients, improved our satisfaction ratings Z percent, secured X more hits on our web site, etc. These points of difference separate you from anyone else that would have had that role or a similar role.

Importantly, avoid qualitative language to define your accomplishments. Most roles have a quantifiable element to them. This is the time and place to use them, regardless of how challenging you might find this step.

Fourth, there is recency bias in reviewing resumes. The positions you’ve held in the past five years are significantly more important than roles you had over 10 years ago. Therefore, weight your resume accordingly. For example, your list of accomplishments should be more robust for recent roles. However, I suggest fewer substantial accomplishments will beat a long list of modest “wins".

For positions that you held over 10 years ago, I suggest using the title and one and at most two key accomplishments that occurred during your tenure in that role. Remember, it is unnecessary to define the responsibilities of entry level or junior positions.

Net, a killer resume has four components:
• It begins with a clear objective of the type(s) of opportunities you desire.
• Each position has two elements, weighted 80/20 to accomplishments, beginning with a brief outline of major responsibilities.
• Provide quantifiable accomplishments for each role
• Skew the emphasis on the document to the most recent five years

Through this approach, hiring authorities will know your desires and can review prior successes demonstrate which suggest your potential to deliver in the future. Importantly, this approach will focus your efforts to seek your next opportunity, within or outside of your current organization.

Dwain Celistan is a retained executive recruiter who focuses on leadership talent. He has authored “5 Simple Steps to Achieving Your Dreams” and “You’re Hired! Actions to Get and Keep the Job You Love”. He can be reached via dwain@reinvent2achieve.com  or 630-455-0172.

by Jean Hollis Weber

Too many editors focus on the details and don't pay enough attention to the bigger picture. Editors can--and should--add even more value through substantive, technical, and usability editing.

Copyediting is important, but the details are only part of what an editor can and should be reviewing. After all, a document can be correctly spelled and punctuated, grammatically correct, use only approved terminology, and follow the style guide perfectly--and still not serve the audience's needs.

This article covers some reasons why editors focus on details and not the bigger picture; describes how much attention technical communicators should pay to formal rules of grammar, punctuation, and usage; and describes how we can distinguish between essential and nonessential rules of grammar, punctuation, and usage.

Why Do Editors Have Such a Narrow Focus?

Some reasons for an editorial focus on details have to do with editors themselves; other reasons arise from the perceptions and priorities of managers and writers.

Many editors are in one of these groups:

• They know how to contribute substantively, but they don't have time--or aren't allowed--to do so.
• They are more comfortable enforcing rules than making critical suggestions and then dealing with writers and others who may not appreciate those suggestions.
• They don't believe they can contribute substantively because they haven't been trained in substantive editing or they aren't sufficiently familiar with the subject matter they are editing.
• They lack the skills to do a good job of copyediting, so they never get the chance to go beyond that stage, even though they might be very good at other types of editing (the skills required are quite different).

Many managers, writers, and other clients believe one or more of the following statements:

• Editors are obsessed with nitpicky details; that's what editing is all about.
• An editor's job is not to substantially revise a writer's work or comment on the technical content or usability of that work.
• Substantive, technical, and usability editing take too long and cost too much.
• Editing is done after the manuscript is written, leaving insufficient time to change anything major that an editor might find.

Distinguish Between Essential, Nonessential, and Fake Rules

How much attention should technical communicators pay to formal rules of grammar, punctuation, and usage? Does incorrect grammar, punctuation, or usage detract from the value and usability of your group's publications? Does your audience care, or even notice, if formal rules are broken?

To answer these questions, we need to examine grammar, punctuation, and usage:

• Grammar is the arrangement, relationships, and functions of words and the ways they are put together to form phrases, clauses, or sentences.
• Punctuation marks are signals that help readers to understand the ideas in a passage and to read more quickly and efficiently.
• Usage is the way in which words and phrases are actually used, spoken, or written in a language community.

   

Rules of grammar, punctuation, and usage can be essential or nonessential--or even fake!

Essential rules are those that are necessary for clear, unambiguous communication.

Nonessential rules are those that are not required for clarity and unambiguity.

Fake rules may actually be matters of word choice, style, or conventional usage, not rules of grammar; or they may be things many of us were taught were wrong, but which are in fact acceptable variations in usage.

Writers and editors need to pay attention to the essential rules, but can spend less time on nonessential rules--particularly in the face of tight deadlines--and they can ignore the fake rules.

Some rules, such as those about dangling participles and not ending sentences with prepositions, are nonessential because readers can figure out the meaning; but they are still important rules to follow in those cases where following the rule would make the writing easier to understand. For example, split infinitives are acceptable in English ("to boldly go"), but if you replace the adverb (boldly) with a long adverbial phrase, the meaning becomes more difficult to decipher.

I'm sure all technical communicators would like to produce perfect documents, but we rarely have the leisure to do so. Business realities too often require compromises from writers and editors, so we place accuracy and usability ahead of minor issues of grammar and punctuation--as I think we should.

Of course, what's a minor issue to me may be a major issue to you; some audiences may have an unusually high percentage of people who won't trust your facts if they think you're misusing the language; and some of your technical reviewers will focus on the grammar instead of the facts. All of these scenarios provide good reasons to pay attention to grammar rules, or at least not abuse them too blatantly or frequently.

Examples of Essential Grammar and Punctuation Rules

Essential rules are those that are necessary for clear, unambiguous communication. Some examples:

Use of commas, when errors can cause ambiguity or misunderstanding. For example, these pairs of sentences convey quite different messages:

• Injured and abandoned by their travelling companions, they managed to stagger to a ranger station.
• Injured, and abandoned by their travelling companions, they managed to stagger to a ranger station.

• Tomorrow will be overcast and rainy at times.
• Tomorrow will be overcast, and rainy at times.

   

Use of apostrophes in possessives and contractions, but not plurals. Incorrect placement of apostrophes changes meaning (often causing confusion or ambiguity) or is completely wrong. Some examples:

• Changes meaning: It's (contraction of "it is" or "it has") or its (possessive of "it");
  who's (contraction of "who is") or whose (possessive of "who");
  the manager's decision (one manager made the decision) or the managers' decision (more than one manager made the decision)
• Just plain wrong: Mens', childrens', its' (all intended to be possessives); video's, photo's (when intended to be plural, not possessive)

Subject-verb agreement (but see notes on "data" and "they," below). When the subject and verb are separated by many other words, this agreement may be difficult to sort out. Often the best solution is to rewrite the sentence: If you can't easily decide whether a verb should be singular or plural, chances are your readers will get lost in the sentence anyway.

Avoiding dangling modifiers, unclear antecedents, and other constructions that can create ambiguity, even when most readers will eventually figure out what's meant. Some examples:

• Dangling modifier: Can occur at the beginning or end of the sentence.
  After reading the original study, the newspaper article is unconvincing. (or)
  The newspaper article is unconvincing after reading the original study.
  (The article--the subject of the main clause--did not read the original study.)
• Squinting modifier: Can relate to a word that comes either before it or after it.
  Players who seek their coach's advice often can improve their game.
  (What happens often--seeking of advice or improvement?)

Examples of Nonessential Grammar and Punctuation Rules

Nonessential rules are those that are not required for clarity and unambiguity. Some examples:

The distinction between "different from," "different than," and "different to."

• "Different from" is traditionally used when the comparison is between two persons or things: My writing style is different from yours.
• "Different than" is more acceptably used where the object of comparison is expressed by a full clause: This town is different than it was 20 years ago.
• "Different to" is chiefly British; in the USA "to" gets little use and is often considered incorrect even though it is an acceptable variation.

The use of old forms of English: Use of the subjunctive ("if he were to do something"), the pronoun "whom" as the objective form of "who," and several other somewhat old-fashioned (though correct) forms of English.

Many (but not all) rules about the use of commas, given that many punctuation "rules" are different in US English and UK English. For example:

Comma after introductory word or (short) phrase or clause:

• Having chosen nursing as a career, Susan enrolled in many science courses.
• Having chosen nursing as a career Susan enrolled in many science courses.

• When he was in high school, he was known only as an athlete.
• When he was in high school he was known only as an athlete.

My rule of thumb is: If I stumble after an introductory word, phrase, or clause and have to re-read to make sure I understood the sentence, then a comma is probably required (or the sentence needs rewriting), but if I don't stumble, then the comma is probably optional, even if traditional usage says it is required.

The distinction between "which" and "that" in some clauses. Although technically there is a significant difference, in most (but not all) cases readers will not misinterpret the meaning of the sentence, and conventional usage varies between US English and UK English: UK English uses "which" in most situations.

Some apostrophe use. For example, does the use of "user's guide," "users' guide," or even "users guide" or "user guide" lead to any confusion or ambiguity? I think not. (But do pick one variation and use it consistently.) Yes, there's a difference: "User's guide" means a manual for one user, whereas "users' guide" means a manual for multiple users. This is a clear grammatical distinction, but to the reader, it's irrelevant: In both cases, the title clearly communicates that the manual is intended to help them use the product. ("Users guide" is technically incorrect but perfectly clear, and "user guide" is common usage.)

Examples of Usage Rules

Style and usage rules may be written into a style guide as "the way we do things here," to improve consistency in a company's publications, but editors and writers need to recognize them as choices, not rules of English grammar.

Another good reason to include some usage rules in your style guide is to clarify what's negotiable in your company and what's not negotiable.

Some examples:

• Punctuation order, for example whether commas and periods (full stops) go inside or outside a quotation mark. Conventions vary between US English and UK English.
• Punctuation and capitalization rules for vertical lists. Several styles are in common use; pick one style and use it consistently.
• Whether "data" is a singular or plural noun. Usage varies; in computing, "data" is typically collective and singular; in mathematics, "data" is usually the plural of "datum." Choose the conventional usage for your audience.

Examples of Fake Rules

• The rules against using split infinitives or ending a sentence in a preposition. You may have been taught these rules in school, but they are based on some decisions made by a few people a century or two ago and are irrelevant to modern communication.
• The rule against using "they/them/their" as a singular indefinite pronoun. In fact, the singular "they" has a long history as being acceptable in English.

Summary

What's the bottom line?

• Realize that copyediting is important, but it is only part of an editor's job.
• Distinguish between grammar, punctuation, and usage rules that are essential for clear, unambiguous communication, and those that are not essential or even irrelevant.
• Recognize that many things we were taught to consider as "rules" are actually style choices or conventions of usage, and that deviations are not necessarily "wrong" but rather "not the way we do it here."
• Include some grammar and punctuation style choices in the style guide to improve grammar consistency.

Acknowledgements

Thanks to Geoff Hart and the students in two editing workshops for their comments on an early draft of this article.

Jean Hollis Weber is a technical editing consultant based in Australia. She has over 25 years of editing experience in scientific, engineering, computing, and other high-tech fields. Jean maintains the Technical Editors' Eyrie Web site, at http://www.jeanweber.com.