About

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

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

Knowledge of etymology is completely unnecessary for using a language. What's necessary is not what words used to mean, but what words mean now. [...] Sometimes it is claimed that an earlier meaning of a word is its literal or real meaning, but really all that can be said is that an earlier meaning is an earlier meaning.

"goofy"



Navigation





<January 2020>
SMTWTFS
2930311234
567891011
12131415161718
19202122232425
2627282930311
2345678

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 1/20/2020

Totals
Posts - 2597
Comments - 2629
Hits - 2,207,761

Averages
Entries/day - 0.43
Comments/entry - 1.01
Hits/day - 365

Updated every 30 minutes. Last: 12:24 PM Pacific


  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?
Cautions
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?
Overdose
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]   ,

|


  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]   ,

|


  11:33 PM

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.")

[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] |


  08:28 AM

There are many reasons to use styles in Word, as I've noted before. One feature I find handy is using styles that have different spell-check options for different types of text. I'll explain a couple of examples: one where I set a non-default spell-check option (Spanish), and another where I disable spell check for code snippets.

Note: If you'd rather see this on video, see the links below.

Spell check for non-default languages

Suppose you're writing a document that has quotations in different languages. If you run spell check over the document, it'll barf when it gets to your citations in Spanish or French or Latin or whatever.[1]

The hard way to solve this problem is to select the text of each citation, one by one, and then to set the proofing language (Review tab > Language > Set Proofing Language).

The easier way to do it is to define a style and set the language for that style. Then you can just apply the style to your citations.

Suppose I'm writing about One Hundred Years of Solitude by Gabriel Garcia-Marquez:


I run spell check, and uh-oh: if it's going to stop on every word of Spanish, it's going to be a long night proofing this doc:


Instead, I'll create a style just for my quotations in Spanish. In this case, I'll create a paragraph style, although I can set language options for character styles also, which is useful for cites in running text.

Here's the Create New Style dialog. The new style is named Quotation in Spanish. It's a paragraph style, based on Normal, and I've set an indent.


Then in the Format options (bottom left), I choose Language:


For the language, I choose Colombian Spanish:


Now I can apply this style to any citations in the document that are in Spanish. When spell check gets to the citations, it switches to checking spelling in Spanish. (Which is handy, since I'm a bad typist in multiple languages.)


If the document contains text in several languages, you create a different style for each non-default language that you're using and apply them as needed.

Disabling spell check for selected text

I don't actually encounter a lot of Spanish citations in my work, but I do encounter a lot of snippets of program code and HTML. I also encounter filenames and URLs that are oddly spelled per English conventions. As with non-English text, this can throw spell check off. So I create a style for code and for HTML blocks and for filenames and for URLs. In those styles, I disable spell check altogether.

Skipping ahead, here's an example of what some sample text looks like when these styles have been applied:


There are 3 styles at work here. The green monospace marks a character style named Code. The blue italics mark a character style named Filename. And the indented block with gray background marks text that's styled using a paragraph style named Pre (a nod to the HTML element name for code blocks).

In addition to the various formatting settings that I defined for these styles (italics, blue, green, monospace, indented, etc.), in each case I chose the Language setting. Then in the Language dialog, I chose Do not check spelling or grammar:


When spell check runs, it skips over any text that has been styled using a style with this setting.

I should note that for code and HTML snippets, it can instead make sense to add the various keywords to your dictionary. (I do this for filenames that I encounter often.) However, defining a style that simply turns off spell check has been very handy for me in the code- and HTML-heavy documents that I work on.

Videos

I made a couple of videos about this also and put them on YouTube:
[1] I do realize that Word can be set to auto-detect languages, and that this works pretty well. But the method I describe here also covers scenarios where auto-detect doesn't work well. (Klingon? Dothraki? Etc.)

[categories]   ,

|


  03:02 PM

As most people discover, there's a class of writing error that spell check just can't help you with. Consider these examples:
  • We recommend that the company shit its resources for better output.
  • The event is open to the pubic.
Run these through spell check, and all is well. Only, of course, it's not.

As I recently learned, Word has a feature that can help find errors like this: an exclusion list. An exclusion list has words that are spelled perfectly fine, but that should be excluded from your documents.

The steps for creating an exclusion list are described in a great blog post by Sam Hartburn. The basic idea is that you add words, one per line, to .lex files in a specific folder on your computer. Here's the Windows location--see notes later for Mac instructions:


You can use any text editor to edit the file, including Notepad.

Note that there are different .lex files for different languages, and in fact for different flavors of each language—e.g. English US and English GB. (It's not inconceivable that there's a way to set up a global .lex file, but I don't know. Leave a comment if you know about that.)

Once you've got your exclusion list(s) updated, close and then reopen Word. Then when you run the spell checker, Word will flag words that are part of your exclusion list:


The examples I've shown here pertain to, you know, taboo vocabulary. Another excellent use for this feature is to flag words that you often mistype but are technically spelled correctly, such as manger for manager or potion for portion. Or you can use it for terms that should be avoided in your particular work, even if they're perfectly cromulent words in English. Really, you can use the exclusion list feature to have Word bring to your attention any word that you might want to double-check as part of your proofing.[1]

I do have a couple of notes for you about using exclusion lists:
  • Words in the list are case sensitive. (As indeed they are in the Word spelling dictionaries.) For example, it's probably a good idea to include both assed and Assed.

  • It's up to you to include all variant forms of a term, including plurals and verb conjugations: ass, Ass, asses, Asses, assed, Assed, assing, Assing, etc.

  • With regard to having different .lex files for different language variants, it will up to you to know what languages are in use in a given document. If a document has been through many hands, it's possible that different sections or paragraphs or even words might be flagged as having different language settings.
I learned about all this from a Twitter thread and specifically from the editor Ashley Bischoff. Not only did she introduce a bunch of us to exclusion lists by pointing to the blog post, she took the initiative to create a Google Docs spreadsheet for collecting words for potential inclusion. The doc is open to anyone. Please contribute!

PS Ashley has a second sheet in the workbook with instructions for both Windows and Mac users on how to update your exclusion lists.


[1] Microsoft alums will recognize this as similar to the Policheck tool, about which I've written before.

[categories]   , ,

[2] |


  04:14 PM

On Facebook today, one of the editors I know, Amy J. Schneider, posted about a habit that some writers have, namely adding a kind of reflexive "successfully" to their sentences. Here's an example, which I'm sure we've all seen variations of:

You haven't just logged off. You successfully logged off. (Thankfully, you didn't unsuccessfully log off.)

I see this all the time, and it bugs me pretty much every time. Just for yucks, I did a search for "successfully" in the documentation set I’m currently working on. I found 1473 instances; here are just a few:
  • Snapshot created successfully.
  • Successfully logged into database.
  • After you have successfully created the file, …
  • Click the Check button to verity that the service can successfully connect to your job.
  • To confirm that the volume was successfully taken offline, …
  • After the device is successfully updated, it restarts.
  • Make sure the test has successfully passed before you proceed.
… and on and on and on.

I ask you: is the word successfully really necessary in any of these instances? I posit that it is not. Moreover, and since I apparently am dispositionally incapable of not doing this, I ask myself "Wait, is there an unsuccessful way for this to happen?"

I reckon I could do a global search-and-destroyreplace on "successfully" in our documentation set without worrying that I would be changing the meaning of anything. (I'm not actually going to do this, just to be clear.) In fact, I'd be shaving nearly 20,000 characters out of the docs. Which is to say—of course—that I'd be shaving those characters successfully.

[categories]   ,

|


  12:23 PM

The linguist Geoff Nunberg has an essay on NPR today in which he tells of his rediscovery of the joys of using exclamation points. As he notes …
Yet writers and editors only pride themselves on expunging the marks, never on sticking them in. When it comes to exclamation points, the only virtue we recognize is self-restraint
This is true. In my work (software documentation), we maintain a tone that is, while not entirely academic, pretty neutral. Just the facts. And facts rarely require exclamation marks.

A story I've told many times: Years (decades) ago when I was learning the craft, I drafted something in which I'd included an exclamation point. My then-manager circled it and added this note: "Nix. Too exciting." I've added very few exclamation marks since then.

Technical docs have been on a path toward more friendliness, it's true. And these days especially, docs might initially be created by people who do not spend their days in the tech-writing trenches. The result is that some of these drafts can have a distinctly marketing feel to them, which of course includes exclamation points. Which I always take out.

And more than one exclamation point? Good lord. From the editor Andy Hollandbeck I learned the word bangorrhea, which is the use of excessive!!! exclamation points. The developer Rory Blyth once summed up this editorial attitude: "The use of more than one exclamation point side-by-side, in any context (except comics), is a sign of mental insanity, a marketing degree from the University of Phoenix Online, or both."

Still. Nunberg points out that exclamation points have discursive purpose in informal writing, "chiefly to signal friendliness." If I examine my emailing habits, I have to admit that I do use them like that. To me there's a pretty obvious difference between signing off an email with

Thanks,

versus

Thanks!

… for example.

And I've also noticed that I use an exclamation-mark-based way to indicate a kind of written eyebrow-raised-in-surprise. Like this:

They said they'd be here at 8:00 am (!)

Apparently over 50 people (!) have accepted the invitation

I'm not sure where I picked up this tic or how widespread it is. But I'm not sure how'd I'd replace it if for some reason I could no longer use it.

Nunberg concludes that he's going all-in on exclamation points again. It's a good thing, I guess, to get a kind of permission to unleash a little positive emotion in one's writing. But it will take me a long time, I think, before I'll be comfortable with documentation that describes how to use the many! great! features of our products.

[categories]   , ,

|


  02:35 PM

Another quick post about Word, primarily for my own benefit (when I forget this later).

Word has several options for how you can paste text:


They are (in order):
  • Keep Source Formatting. This option keeps the original formatting (both character and paragraph formatting), but converts it to direct formatting.

  • Merge Formatting. This option copies basic character formatting (bold, italics, underline) as direct formatting, but does not copy any paragraph formatting.

  • Use Destination Styles. This option copies the text and applies styles that are in the target document. (This option appears only if there matching styles in the target doc.)

  • Keep Text Only. This option copies the text as plain text, with no formatting.
I need the last one (paste plain text) more often than any of the others, so I want it on a keyboard shortcut. You can do this by recording a macro of yourself using the Keep Text Only option. But I realized there's an even easier way—just assign a keyboard shortcut to the built-in PasteTextOnly command.

I keep forgetting that most anything Word can do has a command. If a gesture requires just one command, you can assign a keyboard shortcut directly to it. Maybe writing this out will help me remember.

Update I added a video!


[categories]   , ,

|