Category Archives: Focusing on Readers & Writers

Style Standards for Technical Writing

2 Replies

I’m back (after an extreme hiatus from blogging). Because I’m teaching a new graduate course on style for technical writers, I thought I’d share some of the content I’ve been developing here. If you’d rather watch/listen than read, here’s my 19-minute lecture.

Should professional technical communicators still care about writing style?

Despite the fact that technical communicators do far more than write, there’s evidence that writing skill remains a critical competency. That includes the ability to alter style by manipulating language at the word- and sentence-level. In fact, there’s some evidence that the blending of marcomm (marketing communications) and techcomm (technical communication) within many organizations makes this skill more important than ever. See the results of Lanier’s survey of STC members from a few years ago.

Results from Lanier, Clinton R. (2018). Toward Understanding Important Workplace Issues for Technical Communicators. Technical Communication, 65(1), 66-84.

What is the standard for effective writing style for technical content?

I ask my students to review three sources at the beginning of the course to get them thinking about the answer to this question.

First, I have them watch parts 1 through 3 of the video, UX Foundations: Style Guides and Design Systems, from LinkedIn Learning. Many of our students want to work in UX (user experience) after graduation and most will work with UX professionals. That makes it important to understand what UX has to say about style and standards.

Second, I ask them to read Voice, tone and style: The whys, wheres and hows  by Lauren Pope. Lauren’s a content strategy professional. What students find out is that she talks about style and standards differently from UX pros.

Third, I tell them to study the Mailchimp Content Style Guide. This guide/standard is often held up as an exemplar in the world of web content and UX writing because of its success in establishing a clear brand. They published the 1st version on GitHub in 2015 to make it available to others under a Creative Commons license. Many web content developers have adapted it for their own use.

After reviewing these sources, students should reach several conclusions about the standard for effective writing style for technical content:

  • The terms “style” and “style guide” mean something different to different groups of people.
  • Writing standards are created by people who create and distribute content. They are not handed down from the gods.
  • Organizations create standards to consistently influence the way its employees portray it and the way it is ultimately perceived by the audiences of their communications.
  • There is no single, correct standard for anything related to writing style.

There is no single, correct standard for anything related to writing style.

Let me say a little more about that last point. Here’s an example I share with students.

Standard Chicago Manual of StyleMicrosoft Writing Style Guide
AcronymsA number of expressions are almost always abbreviated, even in regular prose, and may be used without first spelling them out. Many of these will be listed . . . in the latest edition of Webster’s . . .Some acronyms, like USB, FAQ, and URL, are more well known than the spelled-out term. Don’t spell out the term if the acronym is listed in The American Heritage Dictionary . . .
QuotesChapter 13: Quotations and Dialogue with 8 subheadings83 words about pull quotes only
ChatbotsNo contentSection: Chatbots and Virtual agents with 4 subheadings
Demonstrating the lack of a single set of standards for all content

These examples show how standards differ. First, both Chicago Manual of Style (CMoS) and Microsoft Writing Style Guide (MWSG) allow authors to use well-known acronyms (or other abbreviations) without spelling them out the 1st time in certain cases where the acronym is considered equivalent to a word. But CMoS refers to Webster’s dictionary and MWSG refers to American Heritage to determine which acronyms are in their list.

In another comparison, CMoS includes an entire chapter on the use of quotations and dialogue, whereas MWSG includes just a few words about the use of pull quotes–the stylized text used as a type of visual to pull readers into the content. On the other hand, MWSG includes an entire section on standards for chatbots, while a search of CMoS finds no relevant content. 

Content creators must first know which guide applies to the material they’re creating. If you’re working on fiction, CMoS will include essential standards for your edits. If you’re working on a chatbot, however, it will be mostly worthless because it doesn’t address the standards relevant to your material.

There is also a lot to say about defining style vs. voice vs. tone. That’s coming soon. I look forward to sharing what comes next in our quest to master writing style for technical content over the coming weeks!

References to learn more

Here are the references I offer students in this first module of the course, many of which are mentioned in my lecture.

Understand the audience for content you are editing

Leave a reply

Editing should maximize the likelihood the purpose of the content creator’s message is achieved. If the content is supposed to inform, then the audience must be able to comprehend it. If the content is intended to direct, then the audience must comprehend it and also be willing and able to use it. This means editors must know the audience in order to recommend changes.

The best information about an audience comes from testing messages with representative people. Despite increasing the cost of developing content, testing can be done on a shoestring budget. To learn more about testing documents, you can begin with the guidelines on usability testing from the federal government’s plain language site. After testing, a knowledgeable and impartial editor often achieves more with testing feedback than the original content writer.

But editors often don’t have the authority to instigate audience testing. The videos below supplement what appears in Chapter 2 of Revising Professional Writing, 4th edition, a specific system for analyzing an audience without testing.

How sensitive is the audience to the content?

How much expertise does the audience have in the content?

Related Readings

There aren’t many posts here at Pros Write that don’t deal with audience. If you enter “audience” in the search field near the top of this page, you’ll get about 10 results.

Researchers interested in workplace document quality have recognized the limitations of text-focused definitions since at least 1989, when Karen Schriver published Evaluating text quality: The continuum from text-focused to reader-focused methods. (If you want to continue exploring research in this area, start with Dutch researchers like Leo Lentz, Henk Pander Maat, or Michael Steehouder.)

If you want to see the specific research supporting my guidance, there are countless possibilities. You might begin with the following sources.

Austin et al. (2009). Using framing theory to unite the field of injury and violence prevention and response: “Adding Power to Our Voices.” Social Marketing Quarterly,
15(S1), 35-54.

Hersey & Blanchard (1988). Management of Organizational Behavior: Utilizing Human Resources. Prentice Hall.

Hofstede (2001). Culture’s Consequences: Comparing Values, Behaviors, Institutions, and Organizations Across Nations. Sage.

Understand the purpose of the content you are editing

Leave a reply

Tomorrow, my technical editing students at the University of North Texas begin discussing editorial decision-making. The rhetorical context within which content is created is critical to good editorial decisions.

Although the video below was created for professionals who write, I’m using it to teach editors how to think about purpose in nonfiction content.

The video supplements what my co-authors and I put into Chapter 1 of Revising Professional Writing, 4th edition.

Related Readings

There are a handful of posts here at Pros Write that deal with purpose in workplace documents. Just search for “purpose” or “planning” in the field near the top of this page. If you want to see the research supporting my guidance, check out the following sources.

Campbell (2015). Thinking and interacting like a leader: The TILL system for leadership communication. Chicago: Parlay Press.

Quinn et al. (1991). A competing values framework for analyzing presentational communication in management contexts. Journal of Business Communication, 28, pp. 213–232.

 

Does essay writing help you succeed as a writer at work?

Leave a reply

Today’s post is in honor of the National Day on Writing. U.S. students spend years writing essays. They believe they know how to write. (And also often believe that writing is meaningless.) What they do not know is that different rhetorical contexts (different goals, audiences, content) give rise to different ways of organizing and presenting information in effective written messages. That’s called genre awareness.

The situation means you shouldn’t be surprised that workplace novices write workplace documents as if they were some version of a five-paragraph essay. Many non-academics complain. Loudly. Here’s a small selection of such complaints. Feel free to add your own in the comments.

There is definitely evidence that such complaints should be interpreted carefully. (See The myth of job readiness? Written communication, employability, and the ‘skills gap’ in higher education.) That doesn’t mean students gain genre awareness before they enter the work force.

Let me share a story that makes my point. [A version appeared on Pros Write a couple of years ago.] Through some odd luck, Pat was enrolled in a university writing course at the same time she was working as an intern at a food manufacturing company. As part of her internship experience, Pat shadowed her manager-mentor on a safety inspection of the company’s Atlanta manufacturing facility. (I have to thank Ron Dulek for part of this story.) The day before her trip to the plant, Pat’s writing teacher asked the class to write a narrative essay. At the end of the trip, Pat’s mentor asked her to write up the results of the inspection in a compliance memo.  Poor Pat!

Pat decided her plant visit could supply the content for her essay assignment. She wrote the essay first because she was more confident about her ability to please her teacher than her mentor. At this point in her life, Pat had written dozens of essays but not one compliance report or memo. In fact, she had never even seen such documents. She began her essay like this:

On June 3, 2012, I conducted an audit at the Atlanta branch of Allgood, Inc., in regards to safety handling and compliance rules. I was escorted on a tour of the facility by B. A. McCoy, who has served as the Assistant Plant Manager for 17 years.

Once Pat finished her essay, she used it as the first draft of her compliance report. While she revised some of the essay’s content, she left the first few sentences the same.

Pat’s writing teacher assigned her a “B” on her essay. However, Pat’s mentor told her she would have to rewrite the report because it was not acceptable–especially the beginning, which should have stated clearly whether or not the plant was in compliance. Pat’s head almost exploded!  Imagine putting the conclusion first. (If you recognize this story, it’s because I’ve told it in many lectures and wrote about it in my co-authored workbook, Revising Professional Writing.)

Imagine how different Pat’s experience would have been if she had been asked to read even one brief workplace report during her 14 years of formal schooling. And what if a teacher had not only assigned the report as reading but had guided Pat in analyzing the difference in rhetorical contexts among the report, a narrative essay, and The Adventures of Huckleberry Finn? And what if a teacher pointed out that the differences in content, organization, style, and mechanics among those three documents were the result of differences in genre? If all of that happened, Pat would have developed genre awareness. She would have received a rhetorical education that would lead to better workplace success!

Of course, when teachers spend time on genre awareness, they are not aiding students in their quest to ace the essay writing required for academic purposes. I mean the high stakes writing “tests” used to determine college or grad school admissions or scholarship offers. Shame on higher ed!

I salute all of those teachers who promote genre awareness just because it’s best for their students in the long run. Keep fighting the good fight. I’ll be standing beside you.

Plain language requires attention to the audience

Leave a reply

In Part One of my attempt to explain how I understand plain language, I focused on the elements of a text that must be managed to create a plain language document. Anyone who has known me for long, however, could have predicted that I would talk about the rhetorical context of a high quality document in Part Two.  Here come my two cents on understanding plain language as an outcome of an audience’s interaction with a text.

Allow me to give a little background first. Following Aristotle, I like to use the rhetorical triangle.

  • The corner with text refers to the elements of content, organization, style, and mechanics that appear in writing and make up the document itself.
  • The corner with purpose refers to the goal or intent of the writer of the document
  • The corner with audience refers to the recipients of the document.

As I remind my students constantly, all three aspects of the rhetorical context must be considered in order to make judgments about communication quality. In other words, a document is successful only when it fulfills the writer’s purpose for the document’s readers. There’s no such thing as a successful document considered in isolation. Researchers interested in workplace document quality have recognized the limitations of text-focused definitions since at least 1989, when Karen Schriver published Evaluating text quality: The continuum from text-focused to reader-focused methods. (If you want to continue exploring research in this area, start with Dutch researchers like Leo Lentz, Henk Pander Maat, or Michael Steehouder.)

I used the revised email announcement shown below in Part One on defining plain language. And I claimed it was a move toward plain language compared with the original version.

View this document on Scribd

However, the text is likely to fail for any of the following readers:

  • One who is not fluent in English.
  • One with visual impairment.
  • One who doesn’t care about pension plans.

Not surprisingly then, one way to define plain language is to focus on the effect or outcome a text has on its readers — rather than on the text itself.  As PLAIN (Plain Language Association InterNational) states, “Plain language is language understood by its audience.” And some folks prefer not to use the term “plain language” at all because of it implies the focus is on the language or text rather than on the reader.

So what are the desired outcomes of a plain language document on its audience? I suppose the most often mentioned is comprehension. It follows that a common prescription from those interested in better workplace writing is to address an audience as if they have less education than the writer or less expertise in the document topic.  Sometimes this is explained by referring to reading levels. In a 2004 report, William DuBay recommended writing to an general audience at the 7th grade level and lowering this to the 5th grade level when communicating about health, medicine, or safety.

Similarly, in the Securities and Exchange Commission’s A Plain English Handbook, Warren Buffett disclosed

When writing Berkshire Hathaway’s annual report, I pretend that I’m talking to my sisters. I have no trouble picturing them: Though highly intelligent, they are not experts in accounting or finance. They will understand plain English, but jargon may puzzle them.

By the way, that handbook is a terrific, concise guide for implementing plain language within the workplace.

While comprehension may be the king of audience outcomes, it is not the only desirable one. First off, the purpose of some documents requires more than understanding. This is true of any document that includes instructions. In my video tutorial based on Chapter 2: Analyzing Audience of Revising Professional Writing (RPW), I explain that the rhetorical context determines whether writers must address audience ability to understand a message or audience willingness to accept a message — or both. Audience outcomes related to willingness include:

  • usability: whether the audience can use the document to perform a task accurately
  • efficiency: whether the audience can get content quickly and easily
  • credibility: whether the audience believes the content of the document
  • selection: whether the audience selects the document to read

The bottom line: I understand plain language as the outcome of an audience’s interaction with a text, and the outcome includes but is not limited to comprehension. You may have noticed that I have said next to nothing about the third point of the rhetorical triangle. That means you can expect Part Three to address document writers and their purposes for writing.

Plain language requires attention to the writer’s organization

Leave a reply

[This post should have appeared on October 13 to acknowledge International Plain Language Day.  More important, it should have appeared AFTER parts one and two.]

In the first two posts defining what I mean by “plain language,” I have focused on two points of the rhetorical triangle: textual elements like style and organization (Part One) and reader outcomes like comprehension and usability (Part Two). Now it’s time to tackle the third, the writer’s purpose.

This is arguably the aspect of rhetorical context that gets the least attention when it comes to workplace documents. This is logical. For academic writing — you know, the kind of writing done throughout nearly all formal education — the writer has often been promoted as the most important aspect of the rhetorical context.  Take, for instance, the concept of “writing to discover” from Peter Elbow. (Here’s a 2007 interview which will help you understand this perspective on writing.) I’ve written several posts about the unhappy consequences of students learning to write only for teachers (see this early one or this more recent one or my About page). One of the things teachers have in common as an audience of student documents is that they must support this writer-centered view. At least to some extent. I mean the student writer is the focus of a teacher’s professional responsibility.

The emphasis on the audience in workplace writing is critical for helping workplace amateurs focus on the rest of the rhetorical context and become pros. However, as a representative of his or her organization, the workplace writer and his or her purpose for a document is also critical.  Unlike academic writers, whose writing is self-centered, workplace writers must focus on both their audience and the organization they represent.

In my video-tutorial on purpose based on Chapter 1 in Revising Professional Writing (RPW), I categorize a professional’s reasons for writing based on the intended effect on the audience:

  • informing emphasizes tasks and the status quo
  • directing emphasizes tasks and action
  • consulting emphasizes relationships and action
  • valuing emphasizes relationships and the status quo

While these do a good job of describing the immediate aims of the writer’s document, they don’t adequately connect to the overarching organizational goals to which the document contributes.  I’m talking about THE bottom line — money. Whether for-profit or not, every successful organization seeks to maximize revenue and minimize costs. When workplace writers create documents, they affect their organization’s bottom line.

Not long ago, I wrote about selling plain language to your manager. (In fact, a comment on that post is why I started this series on defining plain language.) I argued that a business case for creating quality documents might be the key. Making a business case includes analysis of costs, including risks, and benefits.  Let’s consider a simple, hypothetical business case for creating the email announcement to employees about changes in pension plan contributions — the one referred to in Part One and Part Two. In the table below, I’ve calculated costs for creating both a lower quality and higher quality announcement based on the salary of those involved.

 

Low Quality Document

High Quality Document
1.       Reading time (100 employees’ 50K salary)

$4,200

(10 minutes)

$2,100

(5 minutes)
2.       Writing time (HR writer’s 50K salary)

$12

(30 minutes)

$50

(120 minutes)
3.       Reviewing time before delivery (HR manager salary 90K) (5 employees’ 50K salary)

$0

(0 minutes)

$0

(0 minutes)

$22

(30 minutes)

$60

(30 minutes)
4.       Answering questions after delivery (HR employees’ 50K salary)

$600

(1440 minutes)

$200

(480 minutes)

TOTAL COST

$4,812

$2,432

The lower quality announcement costs less before delivery but results in higher overall cost to the organization due to the greater time required for employees to read the email and for HR employees to answer questions about the email content after delivery. Note that I haven’t tried to calculate benefits related to things like employee satisfaction or compliance with federal requirements. Risk assessment is not my specialty. Nevertheless, those benefits could be converted into dollars for the writer’s organization.

My point with this simple example is that plain language is not only about the text and the audience. Or even the about the writer’s purpose for writing. It’s also about the organization’s goals. While I’ve talked about all three corners of the rhetorical context, there’s one more post coming on understanding plain language. I need to deal with the process involved in creating plain language documents.

Check out the 4th Edition of Revising Professional Writing

1 Reply

The 4th edition of Revising Professional Writing in Science and Technology, Business, and the Social Sciences is now available.  It’s an affordable workbook at $39.95 USD, with over 400 revision and editing problems. Instructors get an answer key plus supplements here on Pros Write (e.g., sample documents, videos, etc.) supporting the principles in the book.

Each of the 21 chapters explains research-backed principles for revising or editing a single element (e.g., informative graphics, bottom line placement, conciseness, pronoun reference, etc.). The succinct explanatory text is followed by revision and editing problems that require increasing levels of expertise within each chapter.

Details:

  • Over 400 revision and editing problems covering rhetorical context, development, organization, style and tone, and mechanics.
  • Problems range from sentences and paragraphs to 11 full-length texts.
  • Examples from a variety of texts: memos, letters, résumés, proposals, instructions, definitions, and reports.
  • All revising and editing problems drawn from the actual writing of college students.
  • Self-contained chapters, allowing flexible use with other textbooks.
  • ISBN 978-0-9767180-6-2

Parlay Press provides exam copies:

Email: mail(at)parlaypress(dot)com
Toll-free fax: 888.301.3116

Your feedback is valued!

Thinking and Interacting Like a Leader ebook released today

4 Replies

The 2nd edition of Thinking and Interacting Like a Leader: The TILL System for Leadership Communication is now available as an ebook on Google Play. The book is a concise guide to help current and future managers become better leaders by building their personal power.

In a nutshell, the TILL system teaches you to manage tone when you manage people. Its focus is deliberately not media specific. But I plan to create a few relevant posts about writing here on Pros Write this fall while using the TILL ebook in my course on leadership communication. (Yes, I do have a day job.) There have been a few guest posts here by terrific former students in that course. In fact, the material in the ebook grew out of my experiences teaching them about the role of language in leadership.

Details for instructors/coaches:

  • 12 chapters with two in-depth application exercises per chapter––one analyzed for students, the other for practice, homework, or quizzes
  • extensive analysis of memos, emails, letters, performance evaluations, and leader-member conversations
  • answers to selected exercises
  • annotated bibliography and suggested readings at the end of each chapter
  • equivalent to ~200 pages
  • $29.99 list price (currently $16.19 USD at Google Play)
  • ISBN 978-0-9767180-7-9

One of the great things about ebooks is that you can read a sample without buying. The 1st two chapters of TILL are available free on Google Play. Thanks to Frank and Kathy at Parlay Press for making it happen.

Comments welcomed!

 

A terrific test for assessing a job candidate’s writing skill

Leave a reply

A few days ago, Lee Salz published Help! My salespeople can’t write! He notes that writing skill has become critical because business-to-business selling involves lots of emails and electronic documents, where face-to-face and phone conversations used to prevail. Salz summarizes a test for assessing a job candidate’s writing skills that is worth sharing.

As a final step of the candidate evaluation process, ask this question: “Please provide us with a one-page plan, one page and only one page, in which you share with us how you will make yourself successful in the role. When can you have this prepared for us?”

Salz says he uses the document produced by the candidate to assess writing skills, as well as several other indicators of success: how well the candidate understands the role he/she would play and whether he/she can meet a self-imposed deadline.

Good stuff!

Learn to analyze a workplace audience to deliver an effective message

1 Reply

Know your audience. This would count as a platitude for good writing without some specifics. So this post provides a specific system for analyzing a workplace audience. That system requires writers to assess two aspects of their situation–the context of their message:  (1) their relationship with the audience and (2) their audience’s readiness to accept the message.

An earlier post used the example of writing a letter soliciting sponsorships for First Tee of Tuscaloosa from local businesses. Here’s what I wrote about audience readiness in that situation.

  1. How much expertise do readers have about the message? For the entire group of readers, the writer guessed there was moderately low knowledge of First Tee, especially of its goals (which focus on life skills rather than golf). This meant the letter has to educate or inform the audience.
  2. How sensitive are readers to the message? Overall, the writer predicted moderately low sensitivity because the sponsorships were cheap and included advertising at the First Tee site and events. But the writer still had to persuade them to act.

As another illustration of the importance of readiness, check out these examples used by Victor Yucco in Framing effective messages to motivate your users.

Today’s mortgage APR: 3.75% for a 30-year fixed mortgage. Save today!

Many, although not all, North American readers are able to understand the message. For those who don’t, additional informative content is needed like a definition for the abbreviation or a comparison of fixed versus variable mortgages.

But even for those who comprehend the message, they may not be willing to accept it. That’s why Yucco presents the following version as an improvement.

Today’s mortgage APR is at an all time low of 3.75%. Complete our pre-qualification form now to lock in this rate. This rate would save you enough money on a $250,000 loan over 20 years to send your child to college when compared to an increase of just 1%, which could happen at any time.

To address audience willingness, the writer created persuasive content, such as emphasizing the need to act now and describing the financial gain from doing so with an example of significance to the target audience.  (Yucco summarizes research on framing based on health research–see below.)

My point here is that an audience must be ready–both able and willing–to accept a message. If you haven’t analyzed your audience’s readiness, your message is likely to be ineffective. The same is true for your need to reflect on your relationship with the audience before you write.

Audience analysis in a workplace setting is explained in Chapter 2 of Revising Professional Writing in Science and Technology, Business, and the Social Sciences (3rd edition). If you’re using that book in an academic setting, you’ll find many exercises that require you to analyze a workplace audience and consider the implications for creating a written message. But here are some additional resources to help anyone master this critical skill:

  • a sample document
  • two brief video tutorials
  • a list of research articles supporting my guidance

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

Sample Document

Review the abatement notice created by me for instructional purposes based on information available from Occupational Safety & Health Administration (OSHA).

  • Writer: the owner of a construction company
  • Readers: the company’s employees and OSHA officials
  • Bottom Line Message: three hazards identified during an OSHA inspection have been addressed
Audience-Hazard-Abatement-NoticeDownload

Video Tutorials

I’ve split the video tutorial on audience into two, shorter ones. The abatement notice is included in both.

Related Readings

There aren’t many posts here at Pros Write that don’t deal with audience. If you enter “audience” in the search field near the top of this page, you’ll get about 10 results. If you want to see the research supporting my guidance, there are countless possibilities. You might begin with the following sources.

Austin et al. (2009). Using framing theory to unite the field of injury and violence prevention and response: “Adding Power to Our Voices.” Social Marketing Quarterly,
15(S1), 35-54.

Hersey & Blanchard (1988). Management of Organizational Behavior: Utilizing Human Resources. Prentice Hall.

Hofstede (2001). Culture’s Consequences: Comparing Values, Behaviors, Institutions, and Organizations Across Nations. Sage.