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

The work you do while you procrastinate is probably the work you should be doing for the rest of your life.

Jessica Hische



Navigation





<December 2018>
SMTWTFS
2526272829301
2345678
9101112131415
16171819202122
23242526272829
303112345

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

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 12/14/2018

Totals
Posts - 2538
Comments - 2589
Hits - 2,103,082

Averages
Entries/day - 0.45
Comments/entry - 1.02
Hits/day - 372

Updated every 30 minutes. Last: 1:57 AM Pacific


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

|


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

|


  08:23 AM

At the end of March I gave a presentation at the ACES conference on "Tips and Tricks for Using Microsoft Word Styles." For years I've taught a class about Word styles at Bellevue College. My experience is that even people who use Word don't necessarily know all the ins and outs of using styles, so when the call for papers for the conference came out, I submitted a proposal. It was accepted, and I was given a 60-minute slot.

I spent a lot of time preparing for the session, agonizing about what material to include. Much of my indecision was because I simply didn't know who my audience would be. Would there be people new to styles? Were all of my tips already old hat to an audience of experienced editors? Plus I only had an hour, which I know from experience seems like a lot of time, but is nothing. (My course at BC runs 6 hours.)

I ended up presenting a quick overview, and then a lightning tour of how to apply, create, and manage styles. Along the way I threw in tips that I reckoned could be useful to even people who had worked with styles: keyboard shortcuts; tips for naming styles; style inheritance; styling TOCs; taming multi-level list styles; and more. There were about 60 people in the room.


Presenting about styles. (Photo: Lindsay Lelivelt)

I got the evaluations back recently. There was enough positive feedback to suggest that yes, it was a useful session and that people got good information from it. Big relief! A number of commenters indicated that they liked "technical" sessions, which I hope means I'll have another shot at a session like this.

What was particularly useful, though, was feedback from people who had suggestions or complaints. There were several classes of feedback that I think I've learned different lessons from.

Not the right level. Some felt it was too advanced; a few others felt it wasn’t advanced enough. (This was, of course, precisely my fear.) The solution here, I think , was suggested by more than one person: the session description should have indicated a lot more clearly what level I was aiming at. I got to write my own session description, so this was well within my control.

The session was fast and there was a lot of (too much) information. Boy, this one is a dilemma. There's only an hour, so how do you make it less rushed? One solution, obviously, is to spend more time but try to get through less information. I guess this is possible if I also do the previous, which is to set expectations correctly about what we'll cover.

No hands on. The conference organizers had told me that people like hands-on sessions, and I can see why. But I know also that when people are following along, the pace is just slower, and I knew we would already be pressed for time. I think a solution here might be to request a longer session time (some 90-minute slots are available), or to think about creating an online course.

No Mac information. Someone noted in a slightly annoyed comment that I was unable to answer questions about Word styles on the Mac. Boy, I really dropped the ball on this one. Although I don't use a Mac myself, I know that many people do, and I should have been able to explain which of my tips did and didn't apply to Macs. I won't give this session again without fixing this issue.

All in all, it was a gratifying experience. As with most teaching, the need to present information cohesively forced me to organize and articulate stuff I had floating around in my head, plus I was obliged to research some corners of Word that I knew about but was fuzzy on. Armed with my list of ways to improve the session, I'll pitch it again for the next ACES in conference.

[categories]   ,

[1] |


  07:38 PM

I was editing something at work today and ran across the phrase lightening fast, with bonus e. This got my attention—I've seen this spelling plenty, but it was an unusual context. So I got to thinking about this spelling and why using lightening for lightning isn't all that unreasonable.

First, it's not uncommon. Using the phrase bolt of lightening as a way to search for the term, I found 10 instances in the COCA corpus versus 206 instances of bolt of lightning. Let's call that a 4–5% hit rate. Thunder and lightning gets 156 hits; thunder and lightening gets 5, which is a somewhat lower incidence of around 3%. But it ain't zero. Point is, people do use the lightening spelling; not a lot, but it's out there in printed materials.

Second, it's not an error that spell checkers can find. Lightening is a perfectly cromulent word in its meaning of "to make or get lighter," as in lightening one's load. It's possible that a grammar checker will find the error; for example, if you write "bolt of lightening," Microsoft Word's grammar checker flags it. But in most contexts, grammar checking is not available.

Finally, it can make sense from a phonological perspective. Unless one's pronunciation is particularly precise, it's not hard to hear or make a vowel between the t and n in lightening. This is a phenomenon known as epenthesis, which is common in many dialects (mason-a-ry, ath-e-lete). And lest those of us with perfect pronunciation should feel too smug, epenthesis is the historical source of some now-standard pronunciations (famously, thunder in English got itself an epethentic d—compare Donner in German).

As with many misspellings, people don't like it. But it's an understandable one, at least. And all that said, I did fix it in the document I was editing. :-)

[categories]   ,

|


  09:17 PM

I was reading an article today about Zika, the viral disease that's causing microcephaly in Latin America. Tragic. But I was taken by a language aspect to the article. At one point, the author writes:
Less pesticide means [...] more mosquito-born diseases.
This spelling appears twice in the article, so it seems to be deliberate. There are a couple of possibilities here, I think.

One possibility is that the writer intends borne, but doesn't know how to spell it. This isn't surprising; they're homophones, after all, and born is anywhere from 20 to 50 times more common than borne, depending on which corpus you examine.

Another possibility is that the writer doesn't realize that he really means borne, i.e., the past tense of bear (mosquito-borne disaease == mosquitos bear [carry] the disease). In that case, mosquito-born is an eggcorn: an error, but one that sort of makes sense, since the disease might be "born of" mosquitos.

In edited text it doesn't show up very much. For example, the COCA database lists only one instance of mosquito-born versus 92 instances of mosquito-borne. But a Google search produces page after page of examples, so the writer here would definitely have seen other examples in print.

All in all, it's a pretty interesting error.

[categories]  

[2] |


  01:56 PM

I hesitate to call "typo!" here, but I did find something odd in the February 1, 2016 issue of The New Yorker (page 45):


In case you can't read it, this is the text, with the oddball term highlighted:

Sarah Palin, the pre-Trump embodiment of populist no-nothingism in the Republican party [...]

I would have expected here the name know-nothingism, which I would have understood as a reference to the Know Nothing movement of the 1850s, which had a strongly nativist bent, and which I assume the author of the NYer article, Ryan Lizza, intended to invoke.

I'm wary of this conclusion, tho, because the NYer is about as rigorously edited a publication as there is in the U.S. today, and it would be surprising, to say the least, to find a typo like this.

What am I missing here?

[categories]   ,

[1] |