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

When the rhythm isn't steady, no one will start to dance. No one will start to smile. No one will start to cheer. Because that's your task when you play in front of people, or when you play for yourself ... you don't smile to yourself if the groove isn't there as you like it to be.

Siggi Mertens



Navigation





<April 2020>
SMTWTFS
2930311234
567891011
12131415161718
19202122232425
262728293012
3456789

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 - 4/3/2020

Totals
Posts - 2610
Comments - 2631
Hits - 2,237,992

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

Updated every 30 minutes. Last: 3:09 AM Pacific


  05:32 PM

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

 

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

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

 

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

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

 

casing. I found this text:

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

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

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

 

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

Outcome: We decided to recommend using We recommend instead.

 

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

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

 

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

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

 

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

Outcome: stet.

 

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

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

[categories]  

|


  08:15 AM

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

What's "good" jargon?

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

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

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

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

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

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

Audience

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

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

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

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

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

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

What's "bad" jargon?

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

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

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

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

How can you tell good from bad jargon?

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

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

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

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

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

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

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

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

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

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

But that's a terrible term!

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

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

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

However, …

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

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

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

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

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

It's not easy

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

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

and lest we forget …

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

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

[3] "editor-facing": jargon?

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

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

[categories]  

|


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

|


  12:07 PM

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

Warning Potentially distasteful content—surgery, unpleasant metaphors.

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

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

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

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

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

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

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

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

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

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

|


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


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

|