mike's web log

When we talk to users about software documentation, we consistently get feedback that they like having screenshots in the docs. But screenshots are a conundrum for a technical writer because they introduce issues for the writer—issues that don't necessarily affect any one reader, but that can reduce the quality of the user experience over time and that have other meta implications. In fact, I'd say that screenshots are a documentation feature where the interests of the reader and writer can be quite at odds, as I'll explain.

• Pros of screenshots
• Cons of screenshots
• Advice for using screenshots

Pros of screenshots

You probably know the advantages of including screenshots in documentation, but let's review. Screenshots have the following benefits:

• Orientation. A screenshot can help the reader understand the layout of a console or window that’s in front of them.

• Compact information. This is the "picture is worth a thousand words" benefit—a screenshot can save the reader from having to read a lot of words. For example, a screenshot can show a computer form with all the values already filled in that the writer otherwise has to describe in text.

• Signposting. A screenshot can reassure the reader that they've done something correctly—"when you're done, it looks like this." A corollary is that if the user isn't seeing the thing you're picturing, they know that something went awry. (I've written elsewhere about signposting in documentation.)

• Chunking /graphical relief. Readers hate "walls of text," meaning long blocks of uninterrupted words. One of the ways that you break up (that is, chunk) text or long procedures is to include graphics. Procedures that include screenshots feel friendlier to readers.

Cons of screenshots

The benefits of screenshots are clear enough that many authors use screenshots enthusiastically. I've seen procedures where every step included a screenshot. However, the following downsides to screenshots are often not immediately apparent:

• Time and resources. When you're working on software documentation, getting a computer system into the proper state where you can snap the correct image takes time. Then there might be additional tasks like adding image files to your content management system, writing alt text, and staging all the screenshots and checking them.

  Sure, it's all part of the documentation process, but it's added friction. The more screenshots, the more friction.

• Space in the document. If you're working on paper-based or PDF-based docs, adding screenshots adds pages to the docs. If you have space or size constraints, this can be an issue. (For the most part, this isn't an issue for web-based documentation.)

• Rendering differences. A screenshot might look fine when you're testing a procedure in a browser window on your 24-inch monitor. But users might be using different form factors. Can users still get the benefit of the screenshot if they're looking at it on a smaller monitor, or on a tablet, or even on a phone?

• Maintenance. As we know, computer UIs change, sometimes frequently. But a screenshot has to reflect the UI that the reader is seeing when they're reading, which might be months after you wrote the procedure and snapped the screenshots. Adding a screenshot means you've given yourself a big ol' maintenance task, because …

  A screenshot that's wrong is worse than no screenshot at all.

  Remember orientation and reassurance from the "Pros" list? An incorrect screenshot disorients and un-assures the reader. It significantly degrades the user's experience and their perception of the document. (This is not just speculation; users tell us this.)

  To add to the issue, there's the burden of re-creating a screenshot to reflect an updated UI. The work that you had to do to create it in the first place you have to do all over again for a new version of that screenshot.

• Searachability. Any text that's inside a screenshot probably isn't searchable. If you take a screenshot of a computer form, the labels and values shown in that screenshot will not be indexed for search.

• Accessibility. Screenshots are not going to be visible to some part of your audience. If someone is using assistive technology like a screen reader, the screenshot is effectively opaque.

• Translatability. If your documentation is translated, you need to think about how screenshots will work in translation. Do the screenshots reflect the UI that someone sees who's using a translated version of your product?

  If your localization process doesn't include translating screenshots, are you okay with non-English readers seeing a graphic that doesn't reflect their UI? If the screenshots are going to be translated, who's snapping the screenshots in localized versions of your product and adding those screenshots to the localized docs?

  Even if you don't have a translation pipeline, it's worth thinking about whether non-English speakers might consume your documentation using machine translation and how screenshots then work for those readers.

Advice for using screenshots

So: users like screenshots, but they can be trouble for writers. I've worked in environments where the default approach was no screenshots, for the reasons stated. How can we reconcile the pros and cons? Here are some suggestions:

• Think about the doc type and audience. Screenshots are more useful in tutorials and quickstarts than in other types of docs. If the document is for someone who's experienced with your product (and you have made this clear in the doc intro, right?), they might already be familiar with its interface and don’t need as much orientation, reassurance, and signposting as someone new to the product.

• Use screenshots judiciously. As you work through a procedure or if you're studying users who are doing that, pay attention to where there are hitches and snags. Use text to guide users through these (more on that in a sec), but note those hitches as places where a screenshot might help. Definitely don't add screenshots only to make a procedure friendlier-looking.

  Obviously, if the interface is so complex that it's difficult to use without visual guidance in the docs, that's a problem for all users. In that case, while you're using documentation to work around issues in the product design, file all the bugs you can about these flaws.

• Don’t rely on pictures alone to convey information. Even if a screenshot can theoretically replace a lot of text, in practice, it shouldn't. Accessibility requirements mean that if you show a filled-in form as a screenshot, you should also describe the form fields and their values in text. The same applies for any document that's going to be translated.

  For all contexts, the writer also has the curse of knowledge: they know why they took the screenshot and what it's intended to convey. But that isn't necessarily clear to readers, so they still need explanations of what the screenshots shows. A screenshot should enhance the writing, it should not replace it.

  

• Focus on the relevant information. Crop to the part of the screenshot that you want users to see. This helps users focus on what you're trying to show them. It's also possible that cropping can future-proof the screenshot somewhat—if there are changes to the UI, perhaps the small part of the UI that's shown by a cropped screenshot might not need to be updated.

  

• Have a maintenance plan. Whenever you snap a screenshot, anticipate as best you can what the UI will look like in a year or two. Create a documentation maintenance plan and include a task to re-run procedures and make sure that all the screenshots are accurate. To put it another way, screenshots are another checklist item in your doc debt, so plan accordingly.[1]

As I say, screenshots are a feature of the docs where readers and writers have different interests. Doc decisions should not put greater weight on what's convenient for the writer versus what's useful for the reader. But we also need to take into account the larger picture of user benefits—accessibility, translation, and the degraded experience that incorrect or out-of-date screenshots provide.

As with other features of the documentation, deciding to use screenshots requires us to take a long view of the content we're creating and how we can best benefit our readers (all of them) for now and in the future.

[1] You really, really learn to appreciate restraint in using screenshots after a big UI change where you had to update 40 or 60 or 100 screenshots in a doc set. [^]

Not long ago, one of the editors at work raised a question in our editing group: do we have any guidance about bolding parts of a sentence in a paragraph? Like this:

The editor asked the author why they wanted to bold things this way. "So they'll stand out visually!" was the reply, or something close to that.

We don't have explicit guidance in our style guide that says "don't bold parts of a sentence just for visual accent," so there wasn't anything we could point the author to. Nonetheless, I've been thinking about this question, and I want to articulate why adding random bolding is not a good idea.

First, formatting "has semantics," as we say at work—when something is italicized or bolded or capitalized or monospace, it conveys information to the reader. Our style guide has guidelines for when we use different types of formatting. For example:

Use bold formatting for UI elements and at the beginning of notices.

Use italics formatting when drawing attention to a specific word or phrase, such as when defining terms or using words as words.

(UI elements means that the text references a button caption or textbox label. Beginning of notices means words like Note: at the start of a note.)

By being very consistent with these guidelines, we help the reader understand not just the words in a sentence, but what their significance is. When a reader sees "Click OK," they know that the bolded OK refers to a button.

We have the additional wrinkle in our texts that they're translated into several languages. Our formatting choices therefore have to be clear to the translators as well. If they see text in bold, they know our guidelines, so they assume that bold text is bold for one of the reasons that we've laid out, and they translate accordingly.

That aside, a fair question (imo) to ask the author is why they need to call out snippets of text in the paragraph in the first place. If the bolded bits are the important ones, then what's all the other text in the paragraph about? Sure, we know that people scan documents and that they don't read them word for word. (For example, see F-shaped Pattern of Reading on the Web: Misundertood, But Still Relevant.) But is using random bolded text the best way to accommodate this approach to scanning? We already have other ways to help readers scan the text: headings, lists, and tables. We can write sections, paragraphs, and even sentences to put the important parts at the beginning or the end.

Moreover, if we're going to use bold to make some parts of a paragraph stand out, what's the algorithm? How do we decide which are the important bits? Do we do this for some paragraphs but not others? In other words, is there some sort of consistent approach to how we're doing this, or is it based on the author's intuition about which text should be bolded?

And importantly, what kind of reading experience are we creating if the text has snippets in bold here and there?

Finally, there's a piece of writerly advice that I learned from the editor June Casagrande. In her piece "A look at the visual component of writing" in the LA Times, she points out the following:

In writing, looks count. In fact, many of the style rules followed so religiously by publishers exist exclusively to make the text easy on the eyes.

[…] some of these more superficial style conventions can give your writing a professional polish, affording your words a subtle air of authority. As a plus, writing that's easy on the eyes does a better job of getting your message across.

After reviewing a number of formatting conventions, she concludes with a strong point: "That's what the pros do." I want this observation framed and hanging above my desk. There are these conventions. Are they right? Are they wrong? It doesn't really matter. That's what the pros do.

If you want your writing to look professional, study professional writing and follow the conventions you see there. If you look at a lot of software documentation, do you see bits and pieces of paragraphs bolded? No. Should you develop your own conventions for your document? Also no. Should your document, among the thousands on our site, exhibit unique formatting conventions? Also also no.

My sense is that many editors agree, as least if "likes" on a tweet are any guide:

The next time we have a discussion about random bolding in a document, at least I'll have my thoughts in order. Whether they prove convincing to an author … well, we'll have to see.

I was listening to a podcast yesterday when it was interrupted with an ad that started like this:

Do you have 30 minutes to spare? Because after just one half hour, you'll never have to worry about a break-in at home again. That's how easy it is to set up a security system from [company name].

My editor brain froze at the point. What I heard was a claim that if you installed their system, you would not be broken into—you would be protected against burglary forever ("never have to worry").

When we technical-edit documents at work, one of our priorities is to check for what we call overclaiming. For example, we stay on the lookout for instances of overclaiming about security, like this:

This product prevents bad actors from hacking your system.

A claim like this simply can't be guaranteed. In the realm of security, the apparent strength of your product might just mean that a hacker hasn't found a flaw in it yet. For example, encryption algorithms that once seemed secure enough to be used by the NSA have been cracked.

We look for overclaiming in any discussion of performance:

Using this product makes your applications three times faster.

We look for it in mentions of costs:

This product reduces your computing costs by 50 percent.

For performance claims, we warn authors that anything that states a number has to have data to back it up. If you say your product is three times faster, you better be able to produce the tests that show this. The same applies to any mention of costs: numbers, please.

And we look for it in any text that involves comparison to other products:

Our product is substantially easier to use than [competitive product].

This claim is problematic in multiple ways. First, what does "easier" even mean? Something that's easy for me might be hard for you and vice versa. And competitive products are a moving target anyway; perhaps our product is "easier" than the current version of product X, but who knows what's in their next release.

So naturally I stumbled over "you'll never have to worry about a break-in at home again." But I thought about it for a bit. First, it's advertising copy, not a technical document on how to configure cloud computing. Maybe there's more wiggle room for wild claims, as in, people aren't expected to interpret these things literally.

I also homed in on the phrase "worry about." With some work, this can be made ambiguous. One idiomatic interpretation is that it means that something won't occur:

A more literal interpretation is that, well, you don't need to worry. This is the type of messaging that insurance companies use: it's not that [thing] won't happen, it's that you can stop worrying about [thing] happening because insurance.

I have a hard time fitting this second meaning onto the ad copy for home security systems. But if I had to defend that statement in court, say, that's what I'd go with.

Speaking of consequences, all of this hypervigilance about overclaiming is of course ultimately about protecting the company. The fear is not just that we'll be shown to have been wrong. ("Sorry.") When people spend vast sums based on assurances that you've given them about security or performance or cost, and when those assurances don't prove true, they might take a litigious turn of mind. At the very least, they're not going to trust you in the future and might look elsewhere to spend their money.

I'm not personally aware of the various companies I've worked for being hauled into court to defend an assertion. ("You said we wouldn't be hacked!") But clearly the lawyercats think about this a lot, and I've certainly participated in my share of fire drills in which we dropped everything to grub through many documents, tweaking some text that was discovered to be overclaim-y.

I would not be surprised to hear an ad from the same company a year from now in which the claim "you don't need to worry about break-ins" has been hedged to something like "Get yourself some peace of mind." If I were editing their copy, that's definitely what would happen.

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

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.

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:

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.

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.

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:

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.

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, empirical 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.

The other day I was taking an introductory training class for some technology at work. There was a slide that outlined the technology, and one of the bullet points had an asterisk next to it. At the bottom of the page was this footnote:

Most strong statements like this are only mostly true. Don’t worry about it.

I had to stop for a while to ponder the pedagogical implications of this footnote.

There's an inherent problem in trying to describe something complicated to a newbie: how do you start? If someone knows absolutely nothing about, say, playing bridge, or verbs in Spanish, or physics, or grammar, you have to give them a large-picture, broad-stroke overview of this thing they're about to dive into.

This is hard. One reason is that people who are familiar with some domain frequently have difficulty coming up with sufficiently high-level overviews that make sense to a beginner. I've had a couple of people attempt to explain the game of bridge to me, but they could not come up with a simple, comprehensible explanation of the bidding process.[1]

A closely related reason is that experts often cannot let go of details. For example, in your first week of Spanish class, the teacher tells you that the verb hablar means "to speak," and that to say "I speak" you cut off -ar and add -o: hablo. And that this is the pattern for any verb that ends in -ar. So to say "I take," you use the verb tomar and turn it into tomo.

Easy! Powerful! Also, of course, only mostly true: there are irregular verbs and reflexive verbs and other fun. But throwing those additional details at you in the first week of Spanish 101 is counterproductive. There will be time to sort out the exceptions later, once you understand some basics.

I took physics in high school, and when you start, you're learning a lot about f=ma. I have memories of homework problems involving blocks being pulled or pushed, and the problems always said something like "… ignoring the effects of air resistance." A beginning physics student has enough to think about when calculating the effect of gravitational acceleration without trying to factor in air resistance and all the other real-life variables that come into play. In fact, there's a well-known joke in the physics community about a "spherical cow" that represents the ultimate in simplifying a model.

One more example. In the linguistics community, it's widely discussed that even if kids are taught grammar, it's not taught very well. People who are experts in grammar will sometimes complain (example) that the explanations we give students are hopelessly simplistic. "A noun is the name for a person, place, or thing," goes a typical definition. This doesn't adequately cover gerunds ("Smoking is bad for you") or concepts ("Orange is the new black") or many other ways in which we noun things.

But this gets back to the point. If you're faced with a classroom of 8-year-olds, how do you tell them what a noun is? Using terms like "lexical category" and "defined by its role in the sentence" is not going to work. You have to start somewhere.[2][3]

And that means ignoring messy details. As one of the commenters on the linked grammar post describes it, "It's quite normal for us to use 'lies to children' in education." Or, to get back to where we started, you sometimes have to make strong statements that are only mostly true.

[1] There are people can do this; it just wasn't the people I was playing with.

[2] By coincidence, I ran across a video that tries to explain what nouns and verbs are. We can have a think about whether this is a description that would be suitable for first-time grammar leaners.

[3] And another! Jed Hartman (of Hartman's Law of Prescriptive Retaliation) also has an entry Coming Down with Noun Syndrome about the challenges of identifying parts of speech. ("[A]s usual, the truth is a little more complicated than we were taught. Oops.")

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:

Better keep this for future reference in case I forget what each button does pic.twitter.com/UO795hO3Xn

— Alex Warren (@alexwarren) May 22, 2018

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