The Doctor is IN!

Why bother with a style guide?

If you write or edit more than one document a day or work with other writers and editors, you need a style guide to provide guidance on style (language conventions with respect to spelling, punctuation, capitalization, and typographic arrangement and display). You can create a style guide at the personal, department, or corporate level (depending on the politics in your workplace).

For example, will you write:

  • Provider Services Department or Provider Services department?
  • Post-operative or postoperative?
  • Bullet points with periods at the end?
  • Zero through nine as words and 10 and above as numerals?

If you want consistency in your documents, you must have a style guide to direct these and hundreds of other style decisions.

Base your style guide on a published style manual

Published style manuals include The Gregg Reference Manual or The American Medical Association Manual of Style. You can buy most style manuals on Amazon. To compare 12 currently published style manuals, download this style manual guide that I wrote with my colleague Elizabeth Frick. (You read that right―the other Elizabeth Frick [Betsy Frick] and I have collaborated on several books and documents).

Here’s the short version of that matrix:

  • For most technical and business documents, consider using The Gregg Reference Manual.
  • For medical documents, you must use The American Medical Association Manual of Style and/or Scientific Style and Format (the CSE Manual for Authors, Editors, and Publishers).
  • For academic publishing, consider The Chicago Manual of Style. This manual is generally not appropriate for technical or business writing.
  • For publishing psychological research, use APA (Publication Manual of the American Psychological Association). APA is generally not appropriate for technical or business writing.
  • For government writing, consider The Gregg Reference Manual and/or the U.S. Government Printing Office Style Manual (GPO Style Manual).
  • For journalism and marketing or sales writing, use AP (The Associated Press Manual of Style).  AP is rarely appropriate for technical or business writing.
  • For software documentation, use the Microsoft Manual of Style or Read Me First.

It’s important to realize that your chosen published style manual merely acts as the basis of your style guide―you can go against or “contra” any of the style manual’s advice. For example, if your chosen style manual requires a period after the abbreviation “Inc.” but your company does not use the period, you could list your style followed by the parenthetical (contra Gregg 122f). In a culture driven by individualism, not having to conform to a style manual on every decision may be comforting if you or others chafe at any hint of being controlled.

On the other hand, it may be even more comforting to know that you don’t have to create a style manual from scratch. Save time and base your style on a chosen published style manual, adapting it to work for your organization.

 

Maybe I do know what I know: Enduring principles for writing for both web and print

In my August newsletter, I shared my angst about whether what I teach in my technical writing classes is really informed by research or is simply based on instinct. My headline read: “How do I know what I know?” (My 8-year-old grandson saw that headline and said, “You just know what you know, Grandma! At least, I do.” Oh, to be always as self-assured as an 8-year-old!)

Fortunately, I’m no longer in angst because I have just read Letting Go of the Words: Writing Web Content that Works, Second Edition, by Ginny Redish, a fellow Fellow of STC. I had not read the first edition because of the book’s subtitle; I don’t write web content for a living nor do I usually teach people who write web content. However, my editor suggested reading Redish’s material on personas, and I got hooked on the whole book.

Ginny’s book confirmed that most of my cherished language beliefs do have a solid research foundation, at least for web readers. I recognize that there are differences between web and print-based reading, but I believe that most of the web principles that Ginny shares will generalize to the printed page as well (this may be an intellectual leap that we could argue).

Here are three principles from Ginny’s book that I also love to teach:

  1. Using color is problematic for at least two reasons: Some readers have color deficiencies, and colors carry cultural connotations that you might not be able to predict (pp. 50-52).
  2. Don’t center text, even in table columns, because centering violates the reader’s need for alignment (pp. 59-60).
  3. Readers seeking information look first at your first paragraph and then at the first words of list items (p. 139), so put the “bottom line on top” (i.e., lead with the most important information).

Although I do agree with most of Ginny’s points and practices, a few left me wondering:

  • She argues in favor of “turning sentences into more visual forms, like lists and tables” (p. 62), and I concur; but I wonder why she lowercases the first letter of each listed point. This practice contradicts what I see in almost all lists in technical writing today (again, I don’t know if any research argues one way or the other).
  • She recommends sans serif typefaces for both web and print-based text (p. 62). I’ve always taught that sans serif is best for web writing, e-mail, and slides, but serif is best for print-based text. I was fascinated to read that the research that claims that serif typefaces are better for sustained reading (print-based text) is now more than 60 years old. Ginny claims that “research on web content has not shown a consistent winner between serif and sans serif for either reading speed or comprehension.” However, her assertion that “preference almost always favors the familiar sans serif fonts [for the web]” is not as definitive as I would like.

Despite these minor concerns, I’m glad that I have studied Ginny’s book―it’s packed with excellent tips and persuasive case studies and makeovers. Above all, I found myself reinforced by her underlying principle: Before writing anything for any audience, always imagine a conversation with the reader:

  • What do they think?
  • What do they know?
  • What do they need to know?
  • What will they do with the information?

I don’t need research to tell me that this consideration of my audience’s wants and needs is valid―it’s just compassionate common sense.

And I’m glad that I had to rethink my assumptions: I had made an assumption that I didn’t need to read Ginny’s book because it was framed to help web writers. It turns out that most of her principles apply to the kind of writing that I do teach, and I wish I had read it earlier.

Grammar lesson: When should you use the word “that”?

One of my loyal readers sent me a question about the use of the word “that”; she said, “I am used to seeing the word ‘that ’ in all instances shown below” and provided four examples. Here’s one:

COPAS guidelines require that the initial billing of joint account charges occurs within a 24-month period.

Her boss had removed the word “that” from all the examples, saying:

 “. . . please be aware the word “that” seldom adds value and can be a major distraction. I have made adjustments both in the attached file and in life. My college English professor told me if I didn’t stop using it, I would get an F. I quit using it and I got a C.”

I told her that I could not support her boss’s deletion. I cited a comprehensive article in Technical Communication, the journal of the Society for Technical Communication.

Based on John Kohl’s argument, here’s what happens to the sentence without the word “that”: the sentence structure places “the initial billing of joint account charges” in the direct object position, but the phrase is actually the subject of an embedded relative clause: “that the initial billing of joint account charges occurs within a 24-month period.”

I see this error all the time in my students’ papers (each of the following sentences would be easier and faster to process if the word “that” introduced the relative clause):

  • Part 11 requires audit trails be secure.
  • Demonstrate the Offset Differential at machine 2 is not value-added.
  • We will ensure clinical practice guidelines are easily accessible to all Providers online.

“But,” my students argue, “you’re adding a word to my sentence!” Of course I am, and of course, I can usually remove another five words from their sentence with careful tightening.

I always recommend using the word “that” after these verbs:

•    believe that
•    confirm that
•    ensure that
•    found that
•    indicate that
•    learned that
•    make sure that
•    reveals that
•    shows that
•    stated that
•    understand that

As always, I welcome your comments, questions, and pushback at efrick@textdoctor.com.

_____________________

John R. Kohl, Improving Translatability and Readability with Syntactic Cues, Technical Communication, Vol. 46, No. 2, May 1999, pp. 149-166.

How do I know what I know?

Don’t worry. I’m not going all metaphysical on you. But I’ve recently begun to question one of my long-held beliefs about writing, and I feel conflicted.

Here’s how it came about: In my last newsletter, I wrote a review of Marcia Riefer Johnston’s new book Word Up! How to Write Powerful Sentences and Paragraphs.

I had high praise for her book, but I did challenge her chapter, “The Last Word,” in which she quotes many revered writing experts who say that the writer’s most important point should be placed at the end of the sentence, paragraph, or document. This structure is also known as the “periodic style,” and Johnston recommends its use for “every genre, from oratory to poetry to memoir.” 

The periodic (left-branching) style is the complete antithesis of what I teach: I believe that the best sentence structure for technical and business writing is right-branching rather than left-branching (see my 2008 blog for more explanation).

To understand left-branching versus right-branching style, compare these two sentences:

  • The functional state of our mold, options for correction, and responsibility are the topics I would like to discuss. [Left-branching: You don’t know until the end of the sentence why the three items are presented at the beginning of the sentence or why they’re important.]
  • I would like to discuss the non-functional state of our mold, options for correction, and responsibility. [Right-branching and clearer because you know immediately why the three items are presented.]

And then I got to thinking about the origin of my faith in right-branching sentences: I had discovered the term in a course on building sentences that I took from The Teaching Company[1], but I have yet to find any evidence-based research that proves that readers process right-branching sentences faster or better than left-branching sentences or vice versa. (I will admit that my search has not been exhaustive. This reminds me of former presidential candidate Herman Cain, who was known to say: “I do not have facts to back this up…”)

Nevertheless, I do believe that right-branching sentences are easier to process and understand than periodic sentences. But I know that it’s not enough to cling to my belief without researching what others have found in the way of evidence, so I’m embarking upon a literature search promptly.

And here’s where you come in: Please help me by taking my brief survey on sentences, which will be a good start toward qualitative research. I’ll proceed from there to quantitative research. Thank you!


[1] Landon, Brooks, Building Great Sentences: Exploring the Writers Craft, The Teaching Company, Chantilly, VA, 2008.


The numbers game

I have frequent requests in my writing classes to explain how to express numbers in technical and business writing. Let me be honest with you: I can’t possibly cover all the variables involved in writing numbers in this brief post. In fact, I could actually shorten this article dramatically if I just said: “Consult your chosen style guide.”

For most business and technical writing, I preach that the style guide of choice is
The Gregg Reference Manual
, which

Gregg Reference Manual

has a 30-page section on how to use figures or words to express numbers (Part 1, Section 4). The first four pages prescribe the basic rules, which I will summarize here:

Use words to represent numbers from 1 through 10 (for example: one, two three . . . ten) and use figures for numbers above 10. (Rule 401)

We sent six people to the conference.

I lost only 11 files when my computer crashed.

Use all figures for 1 through 10 when the numbers need to stand out for quick comprehension or have technical significance (Rule 401).

Cut the wire strip into 1-cm lengths.

Use words to represent numbers at the beginning of a sentence (Rule 401).

Sixteen employees called in sick with the flu.

When two or more related numbers appear in the same sentence, use figures for all numbers if one of the numbers is larger than 10.

We have always sent between 10 and 20 employees to the conference.

Use word style for numbers from 1 through 100 when writing high-level executive correspondence or nontechnical documents such as formal announcements, invitations, or literary texts (rule 404).

Other style guides differ from this advice (for example, The American Medical Association Manual of Style prescribes using figures for numbers 1 and above [with a few exceptions]). Be sure to consult any style guides that you are required to use in your job or industry.

Ready for your quiz? http://survey.constantcontact.com/survey/a07e6x0pxjshbzh3li9/start

My favorite things: As perfect as it gets

I always regret that I cannot be a perfect editor. I aim for perfection, but it rarely happens for me (and I suspect, for other editors).

That’s why I was intrigued with “PerfectIt,” software that states on its website that it “runs a series of tests that suggest possible errors. At each stage it lets you choose whether those should be changed.”

PerfectIt checks for consistency of hyphenation; capitalization; numbers/words; capitalization in headings; abbreviations and acronyms (definitions/spelling); bullets; lists; figures; and tables. All these editing inconsistencies drive me crazy, and having software to flag these issues is a gift. PerfectIt has a lot more features that I don’t use at this point (but you might).

The free trial convinced me that I was missing errors and inconsistencies that were found by PerfectIt, so I bought a single license for $49. I run it as an add-on in Microsoft® Word as my last pass through the document (after global searching, onscreen editing, printing out and proofing, and running spellcheck). It works best on longer documents than shorter ones (apparently because a long document provides a bigger set of examples so that the software can determine the dominant style in the document).

As with any new software, I tested it on a few sample documents before launching it on a crucial project; it does take some self-training, which is enhanced by an excellent 4-page set of instructions. In my first use of PerfectIt, I managed to remove the first letter of each word in a 10-page document.

If you are an editor searching for another tool to help you edit mind-numbing larger documents, try PerfectIt!

(I make no money by recommending this or any other cool products that I like.)

Should you use “and” or “but” to start a sentence?

One of my newsletter readers wrote to ask:

Hi Bette:  Do you agree with the information below? (I’m from the old school, where I was taught never to begin a sentence with “and” or “but.”)

Contrary to what your high school English teacher told you, there’s no reason not to begin a sentence with but or and; in fact, these words often make a sentence more forceful and graceful. They are almost always better than beginning with however or additionally. Beginning with but or and does make your writing less formal?but worse things could happen to most writing than becoming less formal.

Note, though, that if you open with but or and, you usually don’t need a comma: not “But, we did it anyway”; it’s enough to say “But we did it anyway.” The only time you need a comma after a sentence-opening conjunction is when you want to sneak a clause right between the conjunction and the rest of the sentence: “But, as you know, we did it anyway.’

*************************************

I don’t agree with using a coordinating conjunction (“and” or “but”) to start a sentence in formal technical and business writing because a coordinating conjunction, by definition, joins two words or phrases in a sentence. I have no problem with using a coordinating conjunction to start a sentence in informal writing (fiction, poetry, blogs, texts, some e-mails, advertising and marketing writing, and personal writing). However, everyone has a different formality scale in their head. I always urge my writing students to write just a little more formally than their reader might, much as they would dress a bit more formally for a job interview than they might on the job.

Further, I suggest, “When in doubt, don’t.”

That said, it is clear to me that more and more people are writing less and less formally. I don’t think that that shift is always appropriate. I’ll continue NOT using “and” or “but” to start a sentence for all my formal technical, business, and medical communication.

Your thoughts?

 

I don’t like to write…

I always startle my students by announcing that I don’t like to write. I think they probably assume: Surely a writing teacher must just love to write!

I do not like to write because writing is hard work, including writing a blog. But like so many other writers, I love to have written. I also like the fact that through writing, I can deliver helpful information to others.

Here’s what happens when I sit down to write: I immediately have writer’s block. As I preach in my classes, one antidote to writer’s block is getting compulsive about my task. So I set my timer for one hour; chain myself to my desk (well, not literally); and write until the bell rings. Then I reward myself by biking to the gym so I can work out.

When I return to the my writing task again, I repeat the “chaining” event and treat myself again when I am done.

Corny? Yes. Effective? Yes. You’re reading this, aren’t you? I’ll do anything necessary to bribe myself to do what I must. And when your comments and feedback roll in, I’ll be glad I made the effort.

Prolific author Judy Blume shares her thoughts on how writing is like a puzzle: “I’m a rewriter. That’s the part I like best . . . once I have a pile of paper to work with, it’s like having the pieces of a puzzle. I just have to put the pieces together to make a picture.” But you must have the pieces of writing BEFORE you can put them together into a bigger document!

What are you waiting for?

AMWA Toolkit for New Medical Writers

This comprehensive explanation of medical writing has been recently updated and is a comprehensive overview for anyone interested in medical writing or editing. Especially useful is the resources list at the end.

Good job, AMWA!

Why bother to field-test your documents?

I recently taught a class in procedure writing. To engage learners, I usually have them build a product with folding rulers that I give them, and they write a procedure to instruct others to build their product. (A procedure is a series of numbered steps that someone must follow to produce a specified outcome.)

After each group finishes writing their steps, they field-test their procedures on potential end users (another group in the class). In most cases, those users can perform the procedures without a hitch. Sometimes, however, the procedure writers have forgotten to specify if the ruler is to be placed on the table with the numbers up or down; in other cases, they have completely left out a step.

Such omissions occur because when we write, we sometimes unconsciously leave things out that are perfectly obvious to us. When we actually see users engage with our documents, we realize that we need to add, subtract, substitute, or reorder our text.

Of course, field-testing a document takes time, but so does ineffective, confusing, poorly written communication that confuses readers!

All writers need to field-test their documents. Recently, my home-town newspaper reported on a local author, Nancy Mervar, who field-tested her first children’s book, Nana’s Silly Goats, on a third-grade class. “When I have kids do the editing and revisions with me, I can do the best job on the story,” she said. “It’s really coming from the kids rather than an adult’s viewpoint of what the kids want to hear about.” An added bonus of this experience is that the students learn more about the writing process, especially since Nancy will share her revisions with them.

Want your own folding ruler? Send me a story about your experience with field-testing your documents to improve them, and if I use it in a future column or blog,  I’ll send you a folding ruler; you can even pick your color!