I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search

(Supports AND)

Google Ads


Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.


Patriotism is proud of a country's virtues and eager to correct its deficiencies; it also acknowledges the legitimate patriotism of other countries, with their own specific virtues. The pride of nationalism, however, trumpets its country's virtues and denies its deficiencies, while it is contemptuous toward the virtues of other countries. It wants to be, and proclaims itself to be, "the greatest", but greatness is not required of a country; only goodness is.

Sidney J. Harris


<October 2020>



Contact Me

Email me

Blog Statistics

First entry - 6/27/2003
Most recent entry - 9/26/2020

Posts - 2627
Comments - 2636
Hits - 2,303,900

Entries/day - 0.42
Comments/entry - 1.00
Hits/day - 365

Updated every 30 minutes. Last: 8:38 AM Pacific

  12:16 PM

Over the weekend, I bought a recliner at Costco, which my wife laughingly suggested was my admission that I'm an Old Guy. But before I could, you know, recline, I needed to assemble the chair and figure out how to work it. In our modern era, reclining chairs are electronic, which means there are 5 different controls, which in turn means that there is an instruction manual.

The manual has instructions for how to perform the one required assembly step, although tbh I had figured out how to do that without the instructions. There are also pictures of how to plug in the two (!) electronic connections, though again, these were self-evident and had also been designed so they could be plugged in only one way.

The useful part of the instructions was the diagram that showed what the buttons on the control panel do. Ironically, this illustration is very small for, you know, Old Guys. This is it to scale as best I can render it (2 inches wide):

A curious part of the manual is that whoever created the manual decided that they needed to cast the instructions as a set of numbered procedures. Here's step 2, which is one of the more forced applications of a numbered procedure step that I've seen.

Where is step 1, you ask? I'm saving the best part for last. Step 1 concerns a feature of the recliner that I had not previously thought needed instructing:

("While seated in the recliner, enjoy the rock feature which allows you to gently rock backward and forward.")

There's a lot of fun stuff to unpack here:

  • It's step 1.
  • Don't do this while standing next to the recliner.
  • Imperative "enjoy."
  • "The rock feature."
  • Which "allows" you to rock.
  • Gently.
  • Backward and forward, as if there might be other ways to rock in a recliner.

Moments after I read this out loud to my wife it seemed clear that "enjoy the rock feature" has a good chance of entering our familect, as it's called: we now have a stock answer to the question of "What are you doing right now?" "I'm enjoying the rock feature."

But to end on a serious note: numbered procedures ("how-to" documentation) are useful if the reader needs to follow a sequence of steps to achieve a task. Rocking a chair is not a task that requires numbered steps. Understanding what the controls on a control panel do needs reference documentation, not how-to documentation. There are many challenges in technical writing, and one of them is choosing the appropriate style of documentation for what the reader needs.

More dubious guidance: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

[categories]   ,


  10:42 AM

One of the effects of this year's protests is that it has brought about heightened consciousness about language and how it affects or reflects certain thinking. For example, there have been discussions in the editorial community about capitalizing the word Black "in a racial, ethnic or cultural sense."

In the world of IT, we've been discussing the implications of certain terms for a while. The Microsoft style guide has suggested for a over a decade that writers avoid the terms whitelist and blacklist in order to avoid a connotation that white==good and black==bad. (I wrote about this a while back.)

Our own style guide has a section on inclusive language, and it suggests finding alternatives to a range of language that, when you look at it consciously, can have negative connotations or the possibility of offense. In addition to disrecommending the word blacklist, we tell our authors to use alternatives to terms like crippled system, dummy variables, sanity checks, native features, and first-class citizen.

A short digression about cloud technology. (For tl;dr, you can skip to the discussion of terminology.) We work in the world of cloud computing, which has its own concepts and vocabulary. The cloud, as the jokey definition goes, is just using someone else's computer. More specifically, it means using someone else's one or ten or hundreds of computers, because a fundamental benefit of the cloud is that you can adjust computing power as needed. For example, if you have a retail business, your website might need medium power normally, low power during a summer slump, and heavy-duty computing power to handle your yearly sale. The point is that your need for computing resources goes up and down, and rather than having to build out your own data center to accommodate the maximum possible demand (and whose high capacity might mostly just sit idle), you build your system in the cloud and spin up computers (servers) when demand is high, and take them down when they're no longer needed.

In this environment, computers are commodities. Any single computer is just a faceless worker in your overall computing infrastructure. Compare that to the computer sitting on your desk; you've probably personalized how it runs, installed many updates, and otherwise fussed over it. If one of the faceless computers in the cloud crashes, it's not a big deal; another one spins up and carries on the work. On the other hand, if your personal computer crashes, it's usually a disaster.

Ok, back to terminology. To conceptualize the difference between the faceless fleet of computers in the cloud and your personal computer, technologists devised the metaphor "cattle, not pets."[1] If a computer is a quasi-anonymous something that can be replaced any time, it's "cattle"; if it's an indispensable part of your work, it's a "pet."

Some authors love this metaphor, because, undeniably, it has explanatory power. More than once it's appeared in a document I'm editing, and if I question it, I'll be pointed to how widespread the expression is in IT/cloud texts. And we try to use the vocabulary of our audience.

However. One of my colleagues recently pointed out what might be obvious to a lot of people: the expression "cattle, not pets" is … problematic. One of our principles is "avoid unnecessarily violent language," and once you think about it, you realize that there's implicit violence in the metaphor as pertains to the fate of the "cattle." Moreover, there are cultures in which no cow is just "cattle," and for whom the idea of animals being killed is abhorrent. Therefore, we've updated our guidance to "avoid the use of figurative language that relates to the slaughter of animals."

This sets up a tension we sometimes have when we tell writers to avoid terminology that's still common in a field. We might ask authors to avoid whitelist or cattle-not-pets, and they'll point out that these are well-understood expressions and that using some alternative form potentially confuses readers. ("Allowlist? Did you mean whitelist? Why not just say so?") And people might search for these terms and they'll have no joy if they don't appear in our documentation. Plus it can give off the vibe that we don't know our own field.

But change begins at home. Sure, these problematic terms are part of the industry lingo. And we can't just ignore them out of existence. What we often do, then, is to include the expression parenthetically on first mention of the preferred term. So we might suggest something like "Create an allowlist (whitelist)" or "servers as commodities (sometimes referred to as 'cattle, not pets')" to tie the old term in the reader's mind to a new, better one.

We hope that the collective work of consciousness-raising by many editors and writers over a period of time will gradually alter the perception of problematic terms. The work is never truly done, of course, but it has to start somewhere.

PS I should note that not everyone supports the idea of this type of language change; there's plenty of pushback in the IT world against changing to "so-called inclusive language." These things are not easy.

[1] Devised to explain scaling by Bill Baker, adapted for the cloud by Randy Bias.

[categories]   , ,


  09:24 AM

"Fewer your words": advice, not fetish

A couple of weeks ago, a (virtual) discussion broke out among the writers at work about "empty words" and how these should be eliminated. The original posting was about removing phrases like allows you to, helps you to, is intended for, and some others.

The topic generated a lot of interest, and people came to the conversation with different perspectives. One person: "Fluff should be eliminated." Another: More words make it that much harder for people who use assistive devices like screen readers.

You'd think that as an editor, I'd be delighted to see such keen interest among writers in the topic of "fewering your words," as we editors like to joke. There was a lot of advice that seemed helpful. And there were some nuanced points about reducing text too much.

But a number of issues came up that rubbed me the wrong way. I had to think about why that was, and I thought I should write down what I found.

The first thing that bugged me was a suggestion that we could train a machine-learning tool to eliminate these "unnecessary words." The proposer suggested that if there were a large enough training set that showed the work of human editors, this would be a good approach for suggesting changes. And I thought, how do you think grammar checkers work now?

Another thing that bothered me in the conversation was the confident assertion of absolutes. "The phrase in order to is never necessary," was one opinion. Hard disagree, as I explained a while back in the blog post "In order" to clarify meaning.[1]

For that matter, the original assertion that phrases like allows you to, helps you to, and is intended for are fluff was itself an absolute statement that I disagreed with. Many times I've added these with forethought and for good reasons. For example, many times we add the phrase helps [to] at the request of our lawyercats, who are extremely sensitive to what we might be claiming. Put on your lawyer hat for a second and compare the following:

Using our anti-virus tool makes your computer secure
Using our anti-virus tool helps make your computer secure

… and think about which of those statements you'd prefer to defend in court.[2]

Here's another thought: shorter isn't always clearer. By reducing words, you might make it harder to understand a sentence. Or maybe not harder for you, but for someone who's not a native speaker, or for a translator who sees the sentence with very little context.

My biggest objection, though, was with the whole premise that removing "fluff" and "needless words" was the ultimate good. One writer said they liked to see how many words they could eliminate or how many drafts they could go through. I had to marvel at the time that some writers must have to go over draft documentation again and again, and whether those last couple of passes to squeeze out just a few more words are really the best use of that writer's time.

An unnecessary in order to is virtually never the thing that's preventing the reader from finding and using the information they're looking for.

We're in the business of solving the reader's problems with the least amount of friction. Sure, reducing word count can be part of that strategy. But an unnecessary in order to or allows you to is virtually never the thing that's preventing the reader from finding and using the information they're looking for. As an editor, I am way, way more concerned that a document I'm looking at addresses a real user need, and that the reader can find the information as fast as possible, and that the information is presented in an order and at a level of detail that's correct for that reader, and that the information is accurate and complete. I have edited many documents that initially failed in some or all these ways, and it was far more important to take care of these things than it was to worry about "empty words."

Reduce word count when you can, but don't make a fetish of it, and don't turn it into a set of absolute rules ("in order to is never necessary"). Do not make reduced word count some sort of gauge of editing quality. There's a strong likelihood that there are more important things to concentrate on in your document.

[1] The longer I work as an editor, the less I believe that there are any absolute rules about anything to do with usage.

[2] I am not a lawyer, don't cite me on the legal implications of anything I say here.

[categories]   ,


  05:32 PM

One more (maybe) post about the question of jargon in technical documents and how technical editors can tell good from bad jargon. Here are some real-world questions about jargon that came up this week in our shop and how they were resolved.


mTLS. A writer had mutual TLS in a document and then used mTLS later to refer to this. This felt like an initialism that the writer might have invented to make it easier to talk about mutual TLS. But a web search clarified that mTLS is as common initialism in other (i.e. not just our) texts.

Outcome: I added the initialism on first mention—using mutual TLS (mTLS)—and left the existing instances of mTLS.


CIAM. A similar situation. I ran into CIAM as a shortened form of customer identity and access management. I wanted to be sure that the writer wasn't just making up the initialism so I did a web search. It is used in the industry, but curiously, people have slightly different terms for C: customer, consumer, centralized.

Outcome: I made sure we wrote it out on first mention so that our reader would know which of these variants we intended.


casing. I found this text:

The email addresses johndoe@example.com and JohnDoe@example.com use different casing.

I left a query for the author and for another editor whether we were okay with using the word casing for an IT audience.

Outcome: Yes, IT people are familiar with lowercase, uppercase, camel case, etc., and they understand the word casing. (A programmer I know has a quiz that tests your knowledge of casing names.)


prefer [to]. Authors sometimes use prefer word as an imperative verb, as in Prefer using the console for this step, meaning "It's a good idea to" or "We recommend that you" (use the console). It's hard to look for examples of this usage as a verb. We had a discussion among the editors.

Outcome: We decided to recommend using We recommend instead.


[word]-aware, as in healthcare-aware. One of the editors asked whether the term healthcare-aware was okay. Another editor who works with the translators looked into it and determined that it wasn't always clear what the -aware part meant, and that different translators were handling it in different ways. A complicating factor is that -aware is in some of our product names, like Context-Aware Access and Identity-Aware Proxy.

Outcome: For the time being, we're recommending that writers not use the -aware suffix (unless it's part of a product name).


[word]-facing, as in customer-facing. This seems similar to -aware, but there are differences. For starters, a term like customer-facing is in some dictionaries. We had the same concerns as with -aware, but it looks like -facing is better established. We certainly had a lively discussion.

Outcome: None yet; to be discussed at the next style guide meeting.


quiesce. An editor raised an eyebrow about requires you to quiesce the database. Another editor said that it was common in the domain of databases, which we confirmed with a search.

Outcome: stet.


swim lane. The term swim lane was used in reference to a diagram (As shown in the swim lanes in the following diagram). I did a web search and found a Wikipedia article about this concept, suggesting that it's a term that's probably known to people who regularly see this type of diagram.

Outcome: I added a link to the Wikipedia article on first mention in case some readers don't know the term.



  08:15 AM

In a webinar last week on technical editing, I talked about how technical editors need to be mindful of terminology: they need to be aware of the terms that are common in a domain but also be on the lookout for "jargon." There was a follow-up question about how you know which is which, and I don't feel like I did a good job explaining. So here's a second attempt. :)

What's "good" jargon?

Part of the issue is that the word jargon has two meanings. In the "good" sense, jargon is the specialized terminology of a domain. This can be technical terms themselves, words like the following:

  • macula and percutaneous transluminal coronary angioplasty (medicine)
  • commoditization and Gini coefficient (economics)
  • affinitization and instantiation (computer programming)
  • em dash and down style (editing)

These terms have specific, technical meanings to practitioners in the field, and they're going to appear in specialized literature for the field. People who don't know the field quite likely won't know the terms.

Another kind of good jargon comprises terms that are used as a kind of shorthand in the field. They're not necessarily technical terms, but they're words or expressions that everyone in the field knows. Some examples might be well-known abbreviations or shortenings. A few examples:

  • Foley for Foley catheter in medicine
  • mono for monoaural in sound engineering
  • fintech in the investment world
  • sync and DevOps in IT (also, IT in IT, haha)

I say that these terms are good jargon because they work in the service of clear and concise communication. When I'm talking to a group of American copyeditors, I can say things like "AP and Chicago disagree in some of their guidance about hyphenization and passive,"[1] and it's hard to imagine that the audience would not understand this sentence, even though there are abbreviations (AP), shortenings (Chicago, passive) and technical terms (hyphenization, passive).


This of course brings up the question of audience and context. For that sentence about editing, I was explicit that I was talking to American copyeditors. The sentence probably wouldn't be entirely understandable to my wife, let's say (who's in healthcare), and I wouldn't assume that British copyeditors (subeditors) necessarily know the terms AP and Chicago. (They might, but it doesn't seem like a safe assumption.)

A responsibility for the technical editor during developmental editing is to work with the author to determine who the audience is and what they do (or don't) know

As I had noted during the webinar, a responsibility for the technical editor during developmental editing is to work with the author to determine who the audience is and what they do (or don't) know. An article in a specialized journal is going to have a different audience than a post on Medium, and the editor has to take that into account when gauging whether good jargon is appropriate. But if the author and editor agree that the audience has the background to understand this good jargon, there's no reason not to use it.

This can be fuzzy. It's not like there's a single canonical reader for every piece of writing. It's fair for an editor to make queries to the author: Will the reader understand Foley? Do we need to define affinitization? Are you sure that readers know what AP means? Do IT people really say sync for "synchronization"?[2]

Editors lean toward spelling out and defining. This tendency is generally good; the editor is advocating for the set of readers (perhaps small but non-zero) for whom a term is unfamiliar. In many cases, the editor and author might agree to define on first mention, or use the full form, or at least link to an explanation.

But it can be overdone. Spelling out or defining terms that every reader knows can not only be annoying ("Why are you telling me this?"), it can subtly affect the reader's perception of the piece ("Do you think I'm a noob?"). I sure hope never to encounter a text that talks about "amplitude modulation/frequency modulation (AM/FM)" radios. In technical articles for computer programmers, I would strike well-meaning attempts to spell out HTML or API, because if the reader doesn't know these terms, the rest of the article is not going to very comprehensible either.

What's "bad" jargon?

So that's good jargon. What makes for "bad" jargon? One kind of bad jargon is slang. For example, programmers talk about cruft to refer to code that's no longer useful but that hasn't been removed and is still junking up the system. Anyone who's been in the programming world probably knows this term, but it's probably not appropriate in documentation.

Another example of bad jargon is domain-specific terms for a non-domain audience. The issue here is context: words that are perfectly fine in one context and for one audience are problematic for a different context and different audience. An example that I used in the webinar is that terms that might be fine for an auto repair manual might not be acceptable in that same auto's owner's manual.

So-called business-speak (aka corporate jargon) often combines slang and domain terminology. If you read about "having a one-off face-to-face to iterate on the cadence of deliverables" or "the candidate has been actioned and will be onboarded next week," you might throw up your hands at his hopeless jumble of jargon. But it's important to keep in mind that these sentences are (usually) perfectly understandable to people who write these things and to their intended audience. In other words, context is important. Where this becomes a problem is if the text is aimed at someone outside the "speech community" that understands it, like a press release or an all-hands email.

Finally, there are invented terms. For example, I've often seen an author invent an abbreviation or initialism for a gnarly multi-word term because they don't want to have to repeat it. Officially, we frown on this practice, because it introduces unfamiliar terms that the reader has to then keep track of ("What does that mean again?"), not to mention that it might cause problems for translators later.

How can you tell good from bad jargon?

A big question is how a technical editor can tell the good jargon from the bad jargon. As you can probably guess by now, I'm not going to propose any sort of absolute measure.

Back to first principles: who's the audience and what do (don't) they know? I can't emphasize enough how critical this is to sorting out the question of what constitutes acceptable jargon.

But suppose that while technical-editing a piece, you've run up against a term that feels like jargon and you're wondering whether you should allow it. Here's what I would do:

  • Look at the style guide. I don't mean AP or Chicago here; I mean the usage guide you use for the domain. For example, imagine you're reading draft programming documentation and you keep running across foo and bar. Is this okay? If you're at Microsoft, probably yes. Obviously, this means you have to be familiar with the usage guide or guides for the domain you're editing in.

    Corollary: If you don't already have a style sheet, create one to track the decisions you've made about these terms.
  • Research. Do a web search for the term. If you get results, see if they seem to be in the same domain as what you're editing. If it looks like other writers in the field use the term, it might be okay. But be sensitive to whether you're seeing the term in official documentation or in less formal text, like blog entries.

  • Ask other editors. If you have colleagues, discuss it with them. They might have seen the term before and know whether it's acceptable. If you don't have colleagues nearby, put the query out on editor-facing[3] social media, targeting other editors in your field if possible. Include as much context as you can, because, as I keep saying, context is important.

  • Ask the author. Tell the author that a term seems jargon-y to you and you'd like their input it. (I would be careful to phrase the query to make it clear that it seems jargon-y to you, not that it necessarily is jargon.) The author might point you to other examples[4] or to information that can help you both make a decision about keeping or replacing the term.

  • Ask the translators. If the material is going to be translated and if you have access to the people who manage translations, you might be able to ask them. Translators often have databases of terminology; for example, they might reassure you that they can handle foo or onboarding just fine.

In a sense, I'm suggesting that you put the brakes on your hard-won editorial sensibilities. More on that in a second.

Update: I added a post with some real-world examples that illustrate jargon that we encountered and how we resolved questions about it.

But that's a terrible term!

One of the things I noted during the webinar is that it's not the editor's job to pass judgment on terminology. If people in a domain have settled on terms like operationalize or onboarding or upsert, it's not our job as editors to come in later and say "You shouldn't use that term because it's ugly" (or "it doesn't make sense to me" or "I don't like it"). Our concern is not with our personal reaction to a term, but whether it's being used correctly for the audience. As Judith Tarutz says, “The jargon and conventions of technology are sometimes incompatible with or different from the rules of English.”

Our concern is not with our personal reaction to a term, but whether it's being used correctly for the audience

This isn't to say that you have to love every word you encounter. We editors wouldn't be text-sensitive readers if we didn't have aesthetic preferences for language. But there are times when our personal preferences are not the factor by which we judge usage.[5] You might never develop a fondness for the word onboarding or actioned, but that's what folks in HR say, and our concern is that they're using that word correctly and consistently for their audience for this document.

However, …

However, there is an exception. If a term is potentially offensive or triggering, or if it perpetuates harmful stereotypes, then it is our job as editors to bring this to a writer's attention. An example from the world of software is the term whitelist. This was coined to contrast with blacklist. In IT, whitelisting means to explicitly allow something or someone—for example, an email spam filter allows you to create a whitelist of senders whose message you'll accept.

Over the years, we've asked writers to move away from terms that assign good/bad values to black and white. So instead of saying "Add users to a whitelist," we suggest "Add users to an allowlist" or something similar.

This is an ongoing effort, because whitelist is widely used in software. Still, by changing this usage one instance at a time, we're hoping to move writers toward less charged language.

There are other, similar terms that we try to move writers away from. In a couple of instances, this has resulted in some pretty lively discussions. Authors who defend these terms make much the same argument that I was making earlier about good jargon—namely, that when you're writing for a known audience, you should use the vocabulary that that audience knows. Generally, our compromise is to include a term to establish a mapping, something like "Add users to an allowlist (whitelist)." This also helps if the user performs a search for the term. But after that first mention, we don't use the term again.

Authors are usually satisfied with this compromise. But not always. And in those cases, we have to rely on our author-editor relationship to see what we can do.

It's not easy

The original question—how can you tell good jargon from bad jargon?—doesn't have an easy answer. I hope I've provided some context and some useful suggestions. I would love to hear how other tech editors approach this question.

Since we're talking about jargon, let me finish by including links to some funny lists of domain-specific jargon:

and lest we forget …

[1] I don't actually know this is true, but bear with me.

[2] It's always a fun discussion to ponder the past tense form of "to sync."

[3] "editor-facing": jargon?

[4] Embarrassingly, more than once an author has pointed to a similar usage in our own doc set.

[5] I suppose I should add that I feel that any argument to the effect of "But it's degrading English!" is irrelevant, unless someone can show data showing how and how much a usage degrades the language.



  07:09 AM

My life has been blessedly free of the need for pharmacological intervention, but I recently went for a checkup and left with a fistful of prescriptions. Because this routine drug-taking was sort of new to me, I actually read the inserts that came with the several prescriptions because, well, perhaps there was something I needed to know.

The text was hard for me to read, but that was only because it was in such small print—8 points, perhaps less. And there was quite a lot of it. But this technological limitation at aside, I was surprised at how readable the words themselves proved to be. Perhaps—and this is my observation—by design?

Some details. There are about 1230 words in all, which is about two and a half pages. The text is printed in blobs, aka “walls of text.” The only formatting is ALL CAPS and ALL CAPS IN BOLD. The text is not laid out with an eye to scannability. You can get an idea from the following, with a US quarter coin (about 1 inch/24 mm) for scale.

But as I read the text, I noticed that it seems written for clarity. Here’s an example:

Use this drug as ordered by your doctor. Read all information given to you. Follow all instructions closely. Take this drug at the same time of day. Take with or without food. Keep taking this drug as you have been told by your doctor or other health care provider, even if you feel well.

I noticed these things:

  • Sentences are short.
  • Words are (for the most part) simple and direct.
  • Instructions are clear and are written as imperatives.
  • The text anticipates possible reader questions (“… even if you feel well”).

The headings for the text—the ALL CAPS bits—either lead the reader toward instructions or function as a kind of FAQ:

Ingredient name (includes a pronunciation guide!)
Common uses
Before using this medicine
        What do I need to tell my doctor before I take this drug?
        Tell your doctor if …
        Tell your doctor if …
        Tell your doctor if …
How to use this medicine
        How is this drug best taken?
        How do I store and/or throw out this drug?
        What do I do if I miss a dose?
Possible side effects
        What are some side effects that I need to call my doctor about right away?
        What are some other side effects of this drug?
Additional information

It’s not perfect (I’d certainly edit this a bit), but I think a lot of work went into deciding what information to put into this text, how to organize it, and how to phrase it. The result, I think, ends up being pretty readable.

So-called readability scores aren’t considered particularly precise, but I ran the text through Word’s readability checker and got these results:

The averages in the middle are the ones that seem significant to me:

  • An average of 13 words per sentence is great. A study from 2008 suggested that comprehension dips below 90% when sentence are longer than 14 words. (And many sentences in the text are shorter than that.)
  • The average of less than 5 characters per word is also good. This is supposed to index the proportion of monosyllabic—hence “simpler”—words.

The “reading ease” score of 78 is good (out of 100), and of course the “grade level” score of 5.4 is likewise is supposed to tell you that this text is intended to have the same readability as a text aimed at 10-year-olds. (All of this, let us remember, supposedly.)[1]

But the numbers are only an imperfect way of capturing what I think is going on here, namely that the text has been designed to be comprehensible to as many readers as possible. The whole setup of providing instructions for drugs works against the pharmacist and other interested parties. The medium is bad (a printed insert in a prescription bag). A lot of people don't want to read this type of text. Some of the patients might not be strong readers. So the people who created this text tried to distill the information to the essentials and to present them as clearly as possible.

By the way, it doesn’t escape me that this text was almost certainly not written-written; it was probably assembled. I’m sure there’s a database of “drug insert text,” and a computer pulls out individual sentences to create text that’s relevant for a specific drug, and then prints it along with the labels for the pill bottles and the other stuff that’s stuck into the bag. Nonetheless, the result mostly works; not in layout, but in terms of the text itself. I give this a good grade and salute the many people who probably spent a long time putting this whole system together.

[1] By way of comparison, this post clocks in at 2.8 sentences per paragraph, 15.3 words per sentence, and 4.3 characters per word.

[categories]   ,


  12:07 PM

Before M*A*S*H was a TV series and before it was a movie, it was a novel written by someone who'd obviously been an Army surgeon in Korea. I read the book as a teenager, and weird little bits of it stuck with me over the years.

Warning Potentially distasteful content—surgery, unpleasant metaphors.

One that remains oddly relevant to my work is the idea of meatball surgery. Here are a couple of those bits, which concern Captain Pinkham, a newly arrived surgeon who's still trying to get the hang of field surgery.

Captain Pinkham, in particular, still tended to get bogged down in detail. He would become completely absorbed in repairing damage to a hand and ignore or sublimate the obvious fact that the patient could die of his abdominal wounds. Once, in fact, he spent six hours on a case that should not have taken more than two hours and managed to miss a hole in the upper part of the stomach. The patient almost died, early, from too much surgery and, later, from the missed hole.

After Hawkeye catches and fixes this error, he takes Captain Pinkham aside and offers him some advice:

This is certainly meatball surgery that we do around here, but I think you can see now that meatball surgery is a specialty in itself. We are not concerned with the ultimate reconstruction of the patient. We are concerned only with getting the kid out of here alive enough for someone else to reconstruct him. Up to a point we are concerned with fingers, hands, arms and legs, but sometimes we deliberately sacrifice a leg in order to save a life, if the other wounds are more important. In fact, now and then we may lose a leg because, if we spent an extra hour trying to save it, another guy in the preop ward could die from being operated on too late.

I don't do surgery, obviously, and my work doesn't involve life-and-death decisions. (Thank goodness.) Still, this passage stuck with me over the years as a lesson about prioritization.

We normally maintain a doable pace for our edits, and articles get one or more development edit passes and a couple of copy edit passes. But now and then we'll have hard dates, as when articles need to go out that are keyed to an upcoming trade show or product announcement. At rare intervals we might be asked to review something that needs to go out, like, tomorrow.

This type of crunch-mode workload—and especially the hard dates—forces us to prioritize. Or to echo Hawkeye, we might have to practice a form of "meatball editing." If I have 120 pages' worth of articles that will be referenced in presentations starting next Monday at 9:00 AM, I'm going to worry about editorial issues that have big impact. Are the product names right? Are we saying something dodgy about security? Are the code snippets missing or mangled? Are there sentences that just stop halfway through? Under circumstances like these, I usually can't afford the careful scrutiny and multiple re-reads (not to mention the iterations with the author) that are required in order to sort out issues like whether we actually need to include this paragraph, or whether this table would be better as a list, or whether that's an infelicitous use of the passive.

It's not that we don't care about these issues. Given a more leisurely schedule, we'll dig in on the text. (Sometimes, perhaps, to the exasperation of the author, haha.) And we do often get a chance to go back to the pieces that got only a meatball edit and do a more thorough edit.

The expression "meatball surgery" is distasteful; it suggests a crude way to do something that requires finesse, and I hesitated about using the expression "meatball editing." But as explained by Hawkeye, sometimes you need to address the big issues and deal with the small ones later. True for battlefield surgery, and sometimes true for editing as well.



  10:00 PM

There are a variety of editorial truisms: long sentences are hard to read; lists should be parallel; consistency is good. This wisdom is taught, and it's reinforced by personal experience; editors are themselves readers, after all, and they monitor their own reactions when reading.

However, there isn't always hard data that editors can point to to support what experience and insight tells them is true. But sometimes there is, and just this week I ran across something that underscores the editorial push toward consistency, and I was pretty excited about it.

I'm in a linguistics class right now, and one of our lectures was by the linguist Gareth Carrol, who uses eye-tracking studies to understand how people read. He started his lecture by noting that people do not read smoothly across the page, line by line. They stop on words (fixations); they jump (saccades); they back up (regressions). By studying what's happening with these movements, linguists can determine where people are having trouble with a text, and importantly, where they're not.

Heat map from eye-tracking study (source).

In our lecture, he discussed binomials, which are pairs of words linked by and: fish and chips, bread and butter, salt and pepper. An interesting thing about binomials is that they have a conventional order: people say I'm sick and tired of it; they don't say I'm tired and sick of it.

Eye tracking studies have determined that people can read binomials quickly. It's like the brain sees a familiar binomial and says "Oh, I get this" and can flit to the next bit of text. In an experiment, Carrol and his researchers wrote some stories that included invented binomials—pairs like wire and pipes and leaves and grass. These are perfectly normal pairs of words, but not binomials that have a conventional order.

So what did they learn? A couple of things:

  • People took longer to process these unfamiliar (invented) binomials than to process familiar ones. But …
  • If people saw the same invented binomial four or five times in a story, they acclimated to it and were able to process it faster.

To my mind, this translates easily to the editorial guideline of consistency.

Of course, I'm in the world of tech writing. We already know in our world that readers don't really want to read-read; they want information, and the faster, the better. If you want to reduce friction for the reader (that is, reduce fixations), be conventional. Use words consistently and construct text consistently. By doing this, science says that you're reducing the effort that the reader has to make to process the text, and the sooner they can back to doing whatever it is that they were reading about.

[categories]   ,


  09:37 AM

I know how this happens, I do. A tech writer is given a task to "document the product," and it turns out there isn't much to say. But telling the bosses that nope, it's ok, we don't actually need to say anything about this might be perceived as, dunno, not being cooperative. Maybe even suggesting that the writer's job isn't that important.

Anyway, today we have a couple of examples of what might result if the writer (and common sense) does not prevail. First up, we have these, um, helpful instructions that came with a compass that I own:

There must be a universe in which people buy compasses who don't already know what N, E, S, and W mean. I don't believe we live in that universe.

But even that is reasonable compared to the following, which Twitter user Alex Warren posted today:

More dubious guidance: 1, 2, 3, 4, 5, 6, 7, 8, 9

[categories]   ,


  09:46 PM

Suppose you're on vacation and you're driving to a place named Lisbon Falls. You see this sign, so you turn right.

After you turn, you drive for a long time, but you don't see Lisbon Falls, and you start to doubt that you're on the right road. How helpful would it be to see a sign that said "Lisbon Falls—keep going "?

Obviously, we need signposts to tell us where to turn. But sometimes we need signposts to reassure us that we're going the right way. Since I work in documentation, I'm going to talk about this applies when you're writing instructions.

The first and least controversial example is to show the results of the user's action, like this:

This type of signpost reassures the reader that they've run the command correctly, or made the right gestures in the page, or whatever.

A second type of signpost is one that makes sure the reader is properly oriented at the beginning of a procedure. This comes up a lot in the complex tutorials I work with, which might have many separate procedures. What I tell my writers is that at the beginning of each procedure, they should make sure that the user is clear about where they are. Here's an example:

I sometimes get pushback from an author about this if the user isn't changing contexts between procedures. "They should just keep entering commands where they left off!" the author might say. I get this; it can feel like we're sort of stating the obvious. But remember my example at the beginning—sometimes it's helpful just to know that you're on the right road, even if you haven't gotten any indication that you're not.

The final example is one that I see rarely in technical documentation, which is too bad. This type of signposting warns the user of something out of the ordinary: an unexpected result, a long delay, a tricky procedure, or a non-intuitive process. Here's a sort-of example:

During the editing process, I asked the author "Is that period on the end of the cp command correct?" Yes, was the answer, "unfortunately." This might have been an opportunity to actually say to the reader "Hey, that period at the end? That's part of the syntax." But we didn't do that, perhaps because the author felt that the audience for this piece would not have that question. But you can probably think of other examples where a little authorial aside to point out something weird would have been helpful for the reader.

One of my favorite examples of this was an article about installing tools for Python. It included the following refreshingly honest instruction:
See all that stuff flying by? Forget about it.
(I wrote about this a few years ago.)

Talk about reassuring!

Update On Twitter, Leon (@secretgeek) points out another example of signposting that I didn't call out. In the first example earlier, the instruction starts with "Wait 3 to 4 minutes"—this notifies the user that a delay here is to be expected.

All of these examples—indeed, signposting in general—is a matter of putting yourself in the user's shoes. At what point(s) in the user's journey is it helpful to reassure them that they're still driving in the right direction? As an editor—hence, a user advocate—I'll suggest that it's more often than you think.

[categories]   ,

[2] |