Tag Archives: English language

Worried about using plain language?

In honor of International Plain Language Day, I’ll address a common concern about using plain language when writing at work. Will plain style make your audience think less of you? With my colleagues, I’ve published two studies that answer your question. The published sources are listed at the end of this post.

The bottom line:
U.S. workers prefer plain style and perceive writers of plain style as more confident and professional.

Study 1: U.S. workers prefer plain style in writing.

Let me start with clear evidence that plain style is preferred by readers in U.S. workplaces. We tested the preferences of 614 workers for two major style categories by showing them two short passages: one in plain style and one that was not.

We found 76% of workers preferred the plain options. This was true for all workers although a little less so for those in blue-collar jobs. Preferences were the same regardless of gender. Preference for conciseness was lowest among those who did not attend college.

I’ve summarized how we defined plain style if you’re interested.

Conciseness

There were four subcategories of conciseness tested with pairs of short passages.

Subcategory	Plain example	Plain preferred	Not plain example
Nominals (2 pairs)	The first part of this report defined a portfolio and shows how it can benefit Northern Telecom’s investment decisions.	62%	The first part of this report provides a definition of a portfolio and how it can be beneficial to the investment decisions of Northern Telecom.
Expletives (2 pairs)	Fifteen institutions have responded, which should yield sufficient data to complete our analysis.	79%	It is believed that the responses of the 15 institutions we have contacted so far will yield sufficient data to complete our analysis.
Non-requisites (3 pairs)	An Information Flow and Technology audit has revealed a computer problem with the reconciliation process at the end of the banking day.	65%	An Information Flow and Technology audit has revealed that there was a computer problem with regard to the reconciliation process at the end of the banking day.
Hedges (3 pairs)	The degree of uncertainty inherent in dispersion modeling has led to overly conservative decisions about when to abort a mission.	81%	I believe the degree of uncertainty inherent in dispersion modeling has led to overly conservative decisions about when to abort a mission.

Overall, 72.62% (95% CI [0.71–0.74]) of respondents preferred conciseness.

Word Choice

There were five subcategories of word choice tested with pairs of short passages.

Subcategory	Plain example	Plain preferred	Not plain example
Formality (3 pairs)	While working at ACE Electric, I learned much about the electrical trade and believe this experience has given me an appropriate background for the job you’re offering.	88%	While working at ACE Electric, I learned much about the electrical trade and believe this experience has given me a good feel for the job you’re offering.
Grammar (2 pairs)	Although controlled fires are usually designed to serve a single purpose, they frequently have several benefits.	85%	Although controlled fires are usually designed to serve a single purpose, they frequently benefit several.
Homonyms (3 pairs)	The Cahaba River site exceeds all of the minimum criteria for a wetland restoration project.	63%	The Cahaba River cite exceeds all of the minimum criteria for a wetland restoration project.
Connotation (2 pairs)	It may take some time to gain the same product recognition in the foreign market that we have in the US.	87%	It may take some time to gain the same product notoriety in the foreign market that we have in the US.
Jargon (1 pair)	The liquidity of assets, including the balance of the petty cash fund, should be entered in the journal.	75%	The liquidity of assets, including the balance of the imprest fund, should be journalized.

Overall, 79.76% (95% CI [0.79–0.81]) of respondents preferred plain word choice.

Study 2: Readers perceive plain style writers as more (not less) confident and professional.

Plain style also influences how readers perceive writers. Using the same data collected from Study 1, we investigated those perceptions.

We found statistically significant evidence that writers conveyed

confidence by being concise, in particular by avoiding non-requisite words, jargon, and nominals, and by choosing words with standard/plain connotations and grammar
professionalism by avoiding non-requisite words and hedges and by using standard/plain homonyms

See sources to learn more.

Campbell, K. S., Naidoo, J. S., & Smith, J. (2021). When Your Boss Says, “You Need to Sound More Professional”: Writing Style and Writer Attributions. International Journal of Business Communication, 0(0). https://doi.org/10.1177/23294884211025735

Campbell, K. S., Amare, N., Kane, E., Manning, A. D. & Naidoo,J. S. (2017). Plain-Style Preferences of US Professionals. IEEE Transactions on Professional Communication, 60(4), 401-411. https://doi.org/10.1109/TPC.2017.2759621

Shibboleths & White Shoes: 5 Lessons for Editors

1 Reply

This post is a response to comments from readers about my use of “insure” in Editors insure content matches audience readiness for it. I’m using this as a teaching moment for my technical editing students so it might be too long for others. Skip ahead if you just want to get to shibboleths or white shoes or the 5 lessons.

Insure vs. Ensure

On Twitter, one of my blog readers wrote,

I wonder, based on today’s heading, whether you ever make a distinction between insure and ensure.

This comment is similar to an author query by an editor. It’s a good query, in this case, because it can be interpreted as a simple question, and it’s carefully indirect if meant as a suggestion. After all, I didn’t enlist the reader to serve as my blog editor. And, even if I had, a good editor knows that ownership belongs with the author.

My immediate reaction to the query was to reflect on my usage: I use these two terms as synonyms and, for me, “ensure” is more conservative. I would use it in a context more formal than my blog. Later, I checked a couple of dictionaries to make sure my use of “insure” in the heading was standard. (The habit of looking things up is one sign of a good editor.)

My preferred dictionary, Merriam-Webster, as well as the Oxford Dictionary, lists multiple definitions for “insure.” The following ones are relevant to my headline choice:

to make certain especially by taking necessary measures and precautions (M-W)
to secure or protect someone against (a possible contingency) (Oxford)
as a synonym for “ensure” (Oxford)

Here’s what Oxford says about “insure” and “ensure.”

There is considerable overlap between the meaning and use of insure and ensure. In both British and US English the primary meaning of insure is the commercial sense of providing financial compensation in the event of damage to property; ensure is not used at all in this sense. For the more general senses, ensure is the more usual word, but insure is also sometimes used, particularly in US English, e.g. bail is posted to insure that the defendant appears for trial; the system is run to ensure that a good quality of service is maintained

I was surprised to read “ensure” is more common so I investigated a little more. The chart shows the ngram of usage for the two words in books over the past 200 years.

The use of “ensure” increased dramatically around 1950. I’m not sure how my own idiolect diverged from the norm except that I grew up surrounded by linguistically conservative speakers whose usage must have reflected the equivalency of the two terms. “Ensure” is definitely the more recent usage.

As a result of this investigation, I’ll be more discriminating in my use of “insure” in the future. More importantly, this reader’s comment gave me the chance to show my students that, even with almost 30 years of editing experience, I am still actively learning how to do my job better.

Shibboleths

Another reader’s comment on my use of “insure” was more like an edit than a query.

You may wish to change your headline to fix the misspelling: editors ENSURE content matches audience readiness

The phrasing “may wish” makes this an indirect suggestion. But the use of “fix” and “misspelling” clearly classify my word choice as an error, and that prompted me to revisit the topic of shibboleths.

As John Fought explained in the PBS series, Do You Speak American?,

Language has always helped to signify who we are in society, sometimes serving as a basis for exclusion. A Bible story tells how a password, shibboleth, was chosen because the enemy didn’t use the sh sound.“Shibboleth” has since come to signify an emblem of belief or membership, an identifiable sign of those who must stay outside the gate.

The second reader comment categorizes my use of “insure” instead of “ensure” as a shibboleth. My usage signals I’m an outsider. If I want to be an insider, I have to change my language. I’ve already said that, although two dictionaries support my choice of “insure,” my investigation will make me more discriminating in my use of that word in the future. This additional teaching moment concerns the presumption of my error–the judgment about my lack of proper etiquette.

This is where my beliefs probably diverge from those of the reader who made the comment. My training as a linguist means I don’t believe anyone’s language is wrong. Ever. But I know our language can be ineffective in meeting our goals. That belief underlies my career as a writer, editor, and a teacher or coach of writers and editors. Many, perhaps most, editors share the worldview of prescriptive grammar–that language choices can be wrong. For a more detailed discussion of prescriptive grammar within the context of professional writing/editing, see my earlier post about grammar rules. Here’s a summary.

Prescriptive grammar is the result of a movement in England between 1650 and 1800. Influenced by the chaotic political and social climate of the time, four literary giants (Dryden, Defoe, Swift & Johnson) tried to control the English language by forming a regulatory agency. Although the agency did not endure, Johnson’s authoritative dictionary did. So did the men’s haughty conviction that breaking the rules for proper English (as arbitrarily defined by them) constitutes a breach in etiquette. And such breaches are simply wrong. Like wearing white shoes after Labor Day.

White Shoes

A condescending attitude based on arbitrary rules of etiquette continues and is pervasive among editors. A notable exception, editor Stan Carey writes,

Editors are prescriptive by definition, and many would happily call themselves prescriptivist. Outside of work too, some are linguistically conservative by nature, or rather habit. But this is not a necessity for the job, nor, to my mind, does it automatically confer advantage.

I agree a prescriptive attitude is no advantage. In fact, I would say it’s a disadvantage to an editor.

You may wonder how editors can do their work without telling authors they are wrong. Let me make two points.

The first point is that I do recognize most shibboleths. As an editor, I suggest how authors can alter their language in order to pass through the gate if it leads them toward their final destination. If I’m working on behalf of the author, I do not dictate those changes. If I work on behalf of the publisher, I do. But my directives are based on compliance with the chosen style guide–not on judgments of proper etiquette. And I offer suggestions only to people who have invited me to.

The second point is that editors whose attitude is descriptive distinguish between shibboleths that matter and zombie rules. I know rules about ending a sentence with a preposition and using passive voice are the latter type. There has been considerable research in this area over the past 30 years (see further readings below).

John E. McIntyre, editor at the Baltimore Sun, makes the same points in this video.

Some of us choose not to carry on the tradition of looking down on those who wear white shoes after Labor Day. As a teacher, I believe my job is to expand rather than restrict my students’ choices. I want them to understand what it means to choose white shoes on a whole range of occasions. There is no simple right vs. wrong. I want students to learn how to think about language, how it can be managed to achieve rhetorical aims. Then they will be educated enough to make their own informed choices about shoes or language.

As McIntyre says, we should be capable of “judgment rather than adherence to some set of shibboleths.”

5 Lessons for Editors

Authors own their texts.
No editor can ever stop looking things up.
Editors must continue to improve their craft.
Editing often requires choices among multiple, viable options.
All good editorial suggestions are based on an understanding of a text’s rhetorical context.

Readers label you based on your style

Leave a reply

I’m in Seattle at the Association for Business Communication conference. Erin Kane and I will present “Reader Perception of Workplace-Writer Attributes” this afternoon. (Our fellow researchers, Nicole Amare and Alan Manning couldn’t make the trip.)

We had more than 600 working adults in the US tell us

whether they preferred the more plain or less plain version of 21 written passages
what two labels described the writer of their preferred written passage
what two labels described the writer of the written passage they did not prefer

Good news for those who promote a plain style in their teaching or consulting. People do think plain style is more appropriate in a routine workplace email. The plain passages were preferred 80% of the time (±3.17 at a 95% confidence level). While you might think this is obvious, we have found little research that clearly establishes the style we recommend is actually valued by workplace readers. Most existing evidence is anecdotal.

Good news for those who write in a plain style, too. For example, results for one pair of passages testing nominal usage are shown in the bar chart: 70% of our participants preferred the plainer style without nominals (“defines” over “definition”).

The writer of the plain passage was most commonly described as clear and straightforward. The writer of the passage that was NOT plain as inefficient. Telling writers that, based on empirical research, they will be labeled as “inefficient” by most workplace readers when they use nominals is qualitatively different that telling them they shouldn’t use nominals.

We have lots of interesting results to share. Some today. Some in future publications. Thanks to the ABC’s C.R. Anderson Research Fund for supporting our work.

Shibboleths for National Grammar Day

Leave a reply

For National Grammar Day, I’m posting a slightly edited version of “Shibboleths and entering the professions,” which appeared on Pros Write back in 2012. I wrote the original in response to the raised eyebrows after I posted “Language choices can be unsuccessful — but never wrong.” For some readers, my belief that language can never be wrong contradicts with my belief that I can prepare students for writing successfully in the workplace. The apparent contradiction deserved an explanation. So this post is about grammar rules. (I’ll get to “shibboleths” in a minute.)

According to Parker and Riley (two contemporary linguists) in Grammar for Grammarians:

“grammar” is not a simple, unified subject. Rather, it is a cover term for at least four different, and sometimes mutually exclusive, conceptions of grammar: prescriptive, descriptive, generative, and contextual.

My university training as a linguist means I studied the latter three types of grammar rules. (I learned the prescriptive type in elementary school.) My role as a writing teacher means I often interact with people who assume I share the worldview of prescriptive grammar — that language can be wrong. I don’t. Let me explain why not, borrowing from Parker and Riley’s chapter 2 on the prescriptive period.

Prescriptive grammar is the result of a movement in England between 1650 and 1800. Influenced by the chaotic political and social climate of the time, four literary giants (Dryden, Defoe, Swift & Johnson) tried to control the English language by forming a regulatory agency. Although the agency did not endure, Johnson’s authoritative dictionary did. And so did the men’s haughty conviction that breaking the rules for proper English (as arbitrarily defined by them) constitutes a breach in etiquette and is therefore wrong. (You know, like wearing white shoes after Labor Day.) Sadly, even highly educated people don’t know the history behind these vapid rules.

I’ll give you an example. Robert Lowth, who wrote the highly influential A Short Introduction to English Grammar in 1762, is the subject of the portrait in today’s post. He believed there had been a decline in writing standards and that his job was to remedy the decline by formulating a set of rules for proper behavior. One of his rules is called preposition-stranding:

Keep a preposition with its object.

For Lowth and his followers, this means “the party you went to” is wrong, while “the party to which you went” is right. Parker and Riley explain:

The rule apparently is based on the fact that in Latin (as in all Romance languages), prepositions always precede a noun phrase and thus never appear in sentence-final position.

So, you should ask, what is the relevance of Latin as a model for English? Well . . . there is no direct line of development from Latin to English. Rather English evolved from Germanic roots. (I’ve added red circles to the diagram from the 4th edition of The American Heritage Dictionary of the English Language.) Also, English is structurally different from Latin, using few inflections and a basic verb-object order. Too, by Lowth’s time, Latin had been a dead language for more than a milleneum. (No one outside of a monastery spoke it after ~700 AD.) The fact that a dead language doesn’t change, while a living one cannot stop changing was apparently lost on Lowth and his prescriptivist pals.

You should also definitely ask: what were Lowth’s credentials for creating rules for English usage? He served as Bishop of Oxford and was a professor of Hebrew poetry (in other words, The Old Testament). I willingly recognize Lowth’s expertise in reading Hebrew and Latin. He might also have been a good writer. (I can’t judge the performance of 18th century British scholars.) But I won’t grant him expertise over the language I use today. His rule about preposition placement convinces me he had little enough understanding of the language used during his own lifetime.

Because of my studies in English language, I know prescriptive rules like preposition-stranding are shibboleths. As John Fought explained in the PBS series, Do You Speak American?,

Language has always helped to signify who we are in society, sometimes serving as a basis for exclusion. A Bible story tells how a password, shibboleth, was chosen because the enemy didn’t use the sh sound.“Shibboleth” has since come to signify an emblem of belief or membership, an identifiable sign of those who must stay outside the gate.

If my students’ language signals they may not pass inside the gate where professionals reside, I never tell them they’re wrong. I do sometimes tell them their language will elicit negative attention from some workplace readers. But only when they break prescriptive “rules” that count as shibboleths for professional membership. It’s my responsibility to know which rules matter. Because of my studies in writing and business communication, I know ending a sentence with a preposition isn’t one of them. There has been considerable research in this area over the past 30 years (see further readings below).

In a professional writing course, I always explain levels of formality (see my video on word choice) to everyone. I explain grammatical shibboleths to individual students whose usage signals they belong outside the gate: double negatives and subject-verb agreement are two prime examples. As needed, I explain a few other mechanical issues that serve as shibboleths: misspellings, sentence fragments, and comma splices (see my video on punctuation).

What is most sad to me is that so-called language experts (that means most English teachers, who study little, if anything, about language) perpetuate the worldview of your-language-is-wrong with a total lack of awareness. Almost every person I know believes language can be wrong. Many of them are highly educated. But they were denied any real language education. They did not learn that English does not belong to those long-dead, reactionary, literary men of the 18th century who acted as the judges of etiquette based on their own tastes.

I choose not to continue the tradition of looking down on those who wear white shoes after Labor Day. And I choose not to promote the use of shibboleths to teach students how to enter their chosen professions. To me, there is a critical difference between telling students their language is wrong and telling them their language is likely to be unsuccessful in certain situations because it will distract some readers and undermine their credibility. As an educator, I believe my job is to expand rather than restrict my students’ choices.

More on word choice in evaluations of men and women

6 Replies

Today, I’m following up on a short post about the use of the word abrasive in performance reviews for women. Similar discussions of word choice in student evaluations of college professors have been a hot topic in the past week. See Is the Professor Bossy or Brilliant in the New York Times. Or in Inside Higher Ed yesterday:

A law dean last month urged students to stop commenting on female professors’ attire in reviews, noting that they don’t do so in the same way for men.

Professor Benjamin Schmidt provides an interactive chart for viewing the distribution of words used to describe male and female instructors in a range of disciplines based on reviews from RateMyProfessor.com. Use of abrasive, although relatively rare (e.g., appearing twice per million words for accounting instructors), still appears to be linked to gender. The chart plots its use in negative reviews. What’s up with students of criminal justice and political science?

Here are the results for rude. Note that this word is far more commonly used (e.g., between 250 to 850 appearances per million in negative reviews). And it is clearly attributed more often to female than male instructors across nearly every discipline.

I encourage you to do your own searches. And, for those who want to investigate Schmidt’s methodology, he explains details of the sample, etc. on his website.

If the tool itself interests you, it’s called Bookworm. You can use it to explore lexical trends in texts collected by the developers or even in your own.

How to perform the role of “grammar checker” at work

Leave a reply

From beauty by the geeks

Yesterday in “The big grammar quiz of 2014,” the UK’s Management Today published a terrific piece about grammar in workplace writing. Test yourself with their quiz. Then review your score with their key, which includes thoughtful and accurate explanations.

If you rely on Strunk and White’s classic, The Elements of Style, you will resist those explanations. But I remind readers to consider expert opinions from Geoff Pullum in the Chronicle of Higher Education in “50 years of stupid grammar advice” or the MIT lecture with Steven Pinker, “Communicating science and technology in the 21st century.”

If you’re still resisting, check out my post, “Do you know what you’re saying about grammar,” which expands on Jonathon Owen’s “12 mistakes nearly everyone who writes about grammar mistakes makes.” If you’re hungry for another quiz and more thoughtful explanations from an expert, head over to John McIntyre’s “A grammar quiz not for sissies.”

The message here is that helping people communicate in writing is difficult. But not because they haven’t learned a list of grammar rules. (Part of the problem is that there is no single list. To understand the scope of such rules, check out the HUGE project, a database of all English usage guides.) Helping writers is hard because effective language choices cannot be reduced to that kind of list.

Instead, the Management Today piece ends with 10 terrific tips for those whose unofficial role at work is “grammar checker.”

1) Always encourage [writers] to start by thinking about the specific audience: different readers have different needs and expectations.

2) Often, ‘grammar issues’ are actually about context. How formal does the document need to be?

3) Always seek permission to offer writing advice. Lessons remembered from schooldays are deeply ingrained and criticism may be taken personally.

4) Look stuff up – the internet is the biggest reference library in the world (www.oxforddictionaries.com is good for grammar and usage).

5) Help people understand that there often isn’t a ‘right answer’ in grammar; it’s an untidy field that needs judgement.

6) Businesses that write a lot will need a house style to help make decisions. The online Guardian and Economist style guides are a good starting point.

7) If a senior person has a pet grammar peeve, first find out whether it’s justified – it could be. If it isn’t, try to help them over it (although you may end up having to lump it).

8) Blogs and social media are helpful for keeping up with grammar usage issues –Lingua Franca is a good place to start.

9) Some people think it’s okay to be a ‘grammar Nazi’ but, as the term suggests, it’s very unkind to the recipient. Be sympathetic.

10) Don’t forget, older people will always huff a bit about the literacy of the next generation. ‘There is not a single modern schoolboy who can compose verses or write a decent letter,’ William Langland once said – and he was born in 1332.

Thanks to the authors for offering solid advice: Andrew Ingram (Better Business Writing) and Tom Freeman (The Stroppy Editor). In the spirit of promoting those with good sense, here’s the one-minute video for Andrew’s company.

Friday fun with word frequencies

2 Replies

Calling all word nerds! For some Friday fun, try the Macmillan Red Words Game, which tests your awareness of English word frequency. It’s not as easy as you might think. After a couple of tries, my highest score was 195. Can you beat it?

Along the same lines, Roberto Trotta has written an interesting book.

From the big bang to alien worlds, from dark matter to dark energy, from the origins of the universe to its destiny, The Edge of the Sky is a tale of the great discoveries and outstanding mysteries in modern cosmology — with a twist. Astrophysicist Roberto Trotta has used only the 1,000 most common words in the English language to talk about difficult concepts in cosmology in beautifully simple terms that everybody can understand.

I haven’t read the book yet. But the story on NPR is worth a listen. If you visit Trotta’s website, you can even use the 1000-word rules to try writing something yourself.

For the TRUE nerds (researchers), there are word frequency tools galore at Corpus.BYU.edu from the work of Mark Davies.

Friday fun with a passive quiz

Leave a reply

I’ve been meaning to send you over to this grammar quiz from James Harbeck. But first let me remind you to avoid listening to any “expert” who focuses on limiting your stylistic choices by telling you to “avoid passives.” Here are the items you must judge as passive — or not.

An accidental discharge of the firearm occurred.
Palestinian boy, 10, dies as Israeli troops fire on demonstration.
Boy killed in West Bank protest.
It’s fashionable to make the most expressive wine possible.
There should not have been any physical contact in this incident.
In this final dance move, a snap unfastened and part of the bodice tore.
The biggest regret of all the presidency has to have been the intelligence failure in Iraq.
Did you let him go all the way with you?
Many a tame sentence of description or exposition can be made lively and emphatic by substituting a transitive in the active voice.

You’ll have to visit the quiz published by The Week to get Harbeck’s answers. They’re accurate and entertaining. What more could a word nerd want for some Friday fun? (If you like Harbeck’s style, check out Sesquiotica for more.)

How useful are readability formulas?

4 Replies

Not very. I read about some interesting research last spring and meant to write more about it then. Here’s the bottom line. The researchers evaluated 9 of the most commonly used formulas. Here’s how Willingham summarizes their findings:

All of the readability formulas were more accurate for higher ability than lower ability students. But only one—the Dale-Chall—was consistently above chance.

Only the Dale-Chall predicted reading ability better than flipping a coin. Ouch!

In general, writing experts dismiss the utility of readability formulas as a means of improving the quality of writing produced in the workplace. I mentioned the range of methods for evaluating quality before. The ACM Journal of Computer Documentation dedicated an entire issue to the topic of readability to usher in the 21st ~~millennium~~ century (Volume 24 Issue 3, Aug. 2000). I’ve copied their table of contents with live links and available abstracts for those of you with an interest.

	Introduction to this classic reprint and commentaries
	Bob Waite
	Pages: 105-106
	The measurement of readability: useful information for communicators
	George R. Klare
	Pages: 107-121
	Readability and computer documentation
	Gretchen Hargis
	Pages: 122-131
	Traditional readability concerns are alive and well, but subsumed within several more recent documentation quality efforts. For example, concerns with interestingness and translatability for global markets, with audience analysis and task sufficiency, and with reader appropriateness of technical text all involve readability, but often in ways not easily measured by any formula.
	Readability formulas have even more limitations than Klare discusses
	Janice Redish
	Pages: 132-137
	A literature review reveals many technical weaknesses of readability formulas (when compared to direct usability testing with typical readers): they were developed for children s school books, not adult technical documentation;they ignore between-reader differences and the effects of content, layout, and retrieval aids on text usefulness; they emphasize countable features at the expense of more subtle contributors to text comprehension.
	Readability formulas in the new millennium: what’s the use?
	Karen A. Schriver
	Pages: 138-140
	While readability formulas were intended as a quick benchmark for indexing readabilty, they are inherently unreliable: they depend on criterion (calibration) passages too short to reflect cohesiveness, too varied to support between-formula comparisons, and too text-oriented to account for the effects of lists, enumerated sequences,and tables on text comprehension. But readability formulas did spark decades of research on what comprehension really involoves.
	Klare’s “useful information” is useful for Web designers
	Kristin Zibell
	Pages: 141-147
	In many ways the writing principles that Klare recommended 37 years ago to promote high readability scores still apply to web-site design. Behind the pursuit of readability lies audience analysis, a concern with the intellectual level, previous experience, motivation, and reading goals of ones intended audience. Suitably adjusted to take account of online interactivity, those same concerns should guide design work on web structure and interfaces today.
	Readable computer documentation
	George R. Klare
	Pages: 148-168
	Arguing that current approaches to understanding and constructing computer documentation are based on the flawed assumption that documentation works as a closed system, the authors present an alternative way of thinking about the texts that make computer technologies usable for people. Using two historical case studies, the authors describe how a genre ecologies framework provides new insights into the complex ways that people use texts to make sense of computer technologies. The framework is designed to help researchers and documentors account for contingency, decentralization, and stability in the multiple texts the people use while working with computers. The authors conclude by proposing three heuristic tools to support the work of technical communicators engaged in developing documentation today: exploratory questions, genre ecology diagrams, and organic engineering.

Lead your reader through your content with transitions

Leave a reply

Readers understand a message better when writers use explicit signals of what they want readers to get out of a document. Transitions like “unfortunately” are one type of explicit signal. (Headings are another — see Think long-term and be kind to readers with well-formatted documents.) In fact, transitions are also sometimes called logical connectives. Maybe that makes their function more obvious.

Consider two versions of an excerpt from Costco’s 2011 Summary Plan Description (SPD).

For those who don’t enter revised elections within the 30 day deadline, certain automatic changes will apply. If you have declined healthcare you will not be automatically enrolled. If you do have healthcare coverage and you are:

Reclassified from “full-time” to “part-time,” your current medical plan will switch to Choice Plus for Part-Time Employees (HMSA HMO in Hawaii). If you’re currently in the Premium Dental Plan, you will switch to the Core Dental Plan.
Reclassified from “part-time” to “full-time,” your current medical plan will switch to Choice Plus for Full-Time Employees but you will continue to be covered by Core Dental.

When your status changes, your Life and AD&D Insurance coverage will change to the level available to other Employees with the same benefit status and years of Service as you.

For those who don’t enter revised elections within the 30 day deadline, certain automatic changes will apply. For example, if you have declined healthcare you will not be automatically enrolled. However, if you do have healthcare coverage and you are:

Reclassified from “full-time” to “part-time,” your current medical plan will switch to Choice Plus for Part-Time Employees (HMSA HMO in Hawaii). If you’re currently in the Premium Dental Plan, you will switch to the Core Dental Plan.
Reclassified from “part-time” to “full-time,” your current medical plan will switch to Choice Plus for Full-Time Employees but you will continue to be covered by Core Dental.

Also, when your status changes, your Life and AD&D Insurance coverage will change to the level available to other Employees with the same benefit status and years of Service as you.

The version at right, with those three transitions I’ve highlighted in red, will increase comprehension of the content over the version at left. Why should Costco care? Because U.S. (ERISA) law requires that employers deliver SPDs that explain employee benefits “in a manner calculated to be understood by the average plan participant.”

Transitions are briefly explained in Chapter 9 of Revising Professional Writing in Science and Technology, Business, and the Social Sciences (3rd edition). If you’re using that book in a formal setting, you’ll find lots of exercises in that chapter that help you to identify opportunities to use transitions to control a reader’s interpretation in workplace documents. Here are some additional resources to help you learn about their use:

a sample document, including both an original and revised version
a brief video tutorial
a list of research articles supporting my guidance

Enter feedback in the comments below if I can provide you with better resources.

Sample Document

Review the executive summary for a consultant’s report. The document was adapted for instructional purposes from a report produced by TishlerBise.

Writer: employees of the planning consultant
Readers: representatives of the city of Orange Beach, as well as interested citizens and businesses
Bottom Line Message: specific fees on real estate development are recommended to support municipal services on newly developed land

View this document on Scribd

Here’s a revised version of the executive summary with more effective transitions.

View this document on Scribd

Video Tutorial

The executive summary is used in this 12-minute video about transitions in workplace documents.

Pros Write

Communicate Expertise

Tag Archives: English language

Worried about using plain language?

Study 1: U.S. workers prefer plain style in writing.

Conciseness

Word Choice

Study 2: Readers perceive plain style writers as more (not less) confident and professional.

See sources to learn more.

Shibboleths & White Shoes: 5 Lessons for Editors

Insure vs. Ensure

Shibboleths

White Shoes

5 Lessons for Editors

Further Reading

Readers label you based on your style

Shibboleths for National Grammar Day

Further Reading

More on word choice in evaluations of men and women

How to perform the role of “grammar checker” at work

Friday fun with word frequencies

Friday fun with a passive quiz

How useful are readability formulas?

Table of Contents

Lead your reader through your content with transitions

Sample Document

Video Tutorial

Related Readings