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

So this is how liberty dies. With thunderous applause.

George Lucas



Navigation





<June 2021>
SMTWTFS
303112345
6789101112
13141516171819
20212223242526
27282930123
45678910

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

Contact Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 6/6/2021

Totals
Posts - 2636
Comments - 2645
Hits - 2,383,111

Averages
Entries/day - 0.40
Comments/entry - 1.00
Hits/day - 363

Updated every 30 minutes. Last: 11:02 AM Pacific


  09:32 PM

On Twitter recently, DeAnna Burghart reminded us that if you use Microsoft Word, it's important to back up your Normal.dotm file. If the file is overwritten or corrupted, you lose your macros, your keyboard shortcuts, and other goodies that editors rely on.

I've experienced that problem, gah. So a while back, I set up Windows so that it automatically backs up my Normal.dotm file several times a day. I thought it might be useful to show other people how I did this.

Sad note: The information in this post applies only to Windows. I'm sure there's a way to do this on the Mac, but I don't currently know how to do it.

I realize that this is a long post and therefore looks complicated. It isn't, I promise! I added some extra steps to test as you go to try to make sure that you don't Experience Disappointment.

Update: I created a video version of this tutorial!

Background

To back up your Normal.dotm file, you copy it from its default location (i.e., where Word looks for it) to some other location. AFAIK, the default location is always this:

DRIVE:\Users\YOUR-USER-NAME\AppData\Roaming\Microsoft\Templates

For example, my Normal.dotm file is here:

C:\Users\Mike\AppData\Roaming\Microsoft\Templates

You can certainly copy the file manually. But you can also automate the copy process so that Windows copies the file for you. You might sometimes forget to back up your file by hand, but if you automate the process, you never need to worry about it.

What I did—and what I'll show you here—is that I created a script. The script doesn't just copy the Normal.dotm file to another folder. During the copy process, it names the backup file by adding a date and time stamp. For example, the script creates a file that has a name like this:

Normal(2021-04-26 17_49).dotm

You can see that the filename includes the date (Apr 26, 2021) and time (5:49 pm). Timestamping the backup files has two advantages:

  • Each time you run the backup, you make a new, different backup file. This can be useful if Normal.dotm gets corrupted—you have multiple backup versions of the file, some of which (hopefully) are older than when the corruption occurred.
  • You know when the backup was made.

I use two technologies for the automated backup:

  • PowerShell. This is a programming language that lets you automate Windows tasks like copying files. PowerShell has been in Windows since Windows 7, so you don't need to install anything. I have the complete script in this post, so you don't need to know PowerShell; you can just copy and paste the script.
  • Windows Task Scheduler. This is a Windows utility that lets you run tasks—for example, a script—at specific times or at intervals.

Create the PowerShell script

  1. Create a folder named C:\backup on your computer to copy the backup files to.

    You don't have to use this folder; you can use any folder you like. Just make sure that the folder already exists. (The script won't create it.) If you don't use C:\backup, you need to make some minor changes later.

  2. Open a text editor (for example, Notepad ... don't use Word for this), create a new file, and then copy the following script into it:
    # PowerShell script to back up the Word Normal template (Normal.dotm)
    # 2020-Apr-26 Mike Pope
    
    $bu_path = "C:\backup"
    
    $bu_datetime = Get-Date -Format "yyyy-MM-dd HH_mm"
    $source_file = $env:appdata + "\Microsoft\Templates\Normal.dotm"
    $dest_filename = $bu_path + "\Normal(" + $bu_datetime + ").dotm"
    Write-Output $dest_filename
    Copy-Item -Path $source_file -Destination $dest_filename
  3. If you don't want to use the C:\backup folder, change the path in the third line (the one that starts with $bu_path =). Make sure that you don't add a trailing backslash (\) to your path.
  4. Save the file to the C:\backup folder (or your alternative) using the following name:

    back-up-normal-template.ps1

    The .ps1 extension is used for PowerShell scripts.

  5. Close the text editor.

Test the script

Before you create a scheduled task for the script, it's a good idea to make sure it's working on your computer.

  1. Open a Windows command window. (Press Windows+s, then type CMD). You see a command line:

  2. Enter the following command (better yet, copy and paste it):

  3. powershell.exe -ExecutionPolicy Bypass -File "C:\backup\back-up-normal-template.ps1"

    Again, if you're not using C:\backup, substitute your folder name.

    The command invokes PowerShell and tells it to run the script that's in the back-up-normal-template.ps1 file that you created earlier. The ExecutionPolicy argument tells PowerShell that your script is safe; if you don't include this part, PowerShell will refuse to run the script due to security concerns.

    If all goes well, the script displays the name of the backup file, like this:

    C:\backup\Normal(2021-04-26 17_59).dotm

    If you see red text, read it carefully. Carefully check the command that you entered. You might also need to fix the script itself (the .ps1 file). Some possibilities:

    • The script you used earlier assumes that the Normal.dotm file is in the default location. If the file is in a different location, it's possible the script isn't finding it.
    • If you're not using the C:\backup folder, did you fix up the script to reflect the folder that you are using?

    You must resolve any errors before you can proceed.

  4. If the script appeared to run correctly, look in the C:\backup folder (or the folder you are using instead). Do you see a .dotm file that starts with Normal followed by a date and time? If so, everything is working.

Schedule the backup

You can now configure Windows to run your script at intervals. You do this by creating a scheduled task. When you create the task, you specify what you want to run (the PowerShell command that you just tested) and when you want to run it.

  1. Open the Task Scheduler app. (Press Windows+S, then type Task Scheduler.)

  2. In the folder tree on the left, right-click Task Scheduler Library and then click New Folder. Name the new folder My Tasks. This step isn't essential, but it makes it easier for you to find your custom task later if you want to modify it.

  3. Right-click the My Tasks folder and click Create Task. This opens the Create Task dialog, which has several tabs that you'll be working in.

    Note: Don't close the Create Task dialog (that is, don't click OK), until you've done all the steps.

  4. In the General tab, do the following:

    1. In the Name box, enter the name BackupNormalTemplate.

    2. In the Description box, enter details about what this task is about.

  5. Go to the Actions tab and click New. This is where you specify what you want to run—namely, the PowerShell script.

    1. In the Program/script box, enter powershell.exe.

    2. In the Add arguments box, enter the following:

      -ExecutionPolicy Bypass -File "C:\backup\back-up-normal-template.ps1"

      These settings specify that you want to run the PowerShell script that you tested at the command line earlier.

    3. Click OK to close the New Action dialog and return to the Create Task dialog.

  6. Go to the Triggers tab and click New. This is where you specify when (how often) to run your script.

    1. Under Advanced settings, select the checkbox next to Repeat task every.

    2. Enter an interval for how often you want to run the script. For example, to run the script twice a day, enter 12 hours. (It doesn't look like it, but you can type in that box.)

    3. In the for a duration of list, choose Indefinitely. This tells Windows to keep running the script until you change the interval or delete the scheduled task.

  7. Click OK to close the New Trigger dialog.

  8. In the Create Task dialog box, click OK.

Note: Don't close the Task Scheduler window yet.

Test the scheduled task

You know that the script runs; now you want to make sure that the scheduled task works.

  1. In the Task Scheduler, in the file tree, click the MyTasks folder. The list of scripts in that folder is displayed on the right.

  2. In the right-hand pane, right-click the BackupNormalTemplate task and then click Run.

    The PowerShell scripting window appears briefly, then vanishes.

  3. Go to the C:\backup folder and check that another backup copy of the Normal.dotm file has been saved.

    If this worked, you should be all set.

  4. Close the Task Scheduler app.

You probably want to check the C:\backup folder tomorrow and the next day to make sure that the script is writing out backup files at regular intervals.

If you need to recover a Normal.dotm file, go to the C:\backup folder, rename one of the backup files to just Normal.dotm, and then copy it back to the folder where Word keeps the template.

Hopefully you'll never need to do that. But if you do, you'll have a recent backup available!

[categories]   , ,

|


  08:54 AM

The hazards of overclaiming

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

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

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

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

This product prevents bad actors from hacking your system.

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

We look for overclaiming in any discussion of performance:

Using this product makes your applications three times faster.

We look for it in mentions of costs:

This product reduces your computing costs by 50 percent.

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

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

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

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

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

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

What if we run out of Cheetos tonight?
You don't need to worry about that[, we just went to Costco].

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

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

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

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

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

[categories]   , ,

|


  12:16 PM

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

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

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

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

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

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

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

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

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

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

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

[categories]   ,

|


  10:42 AM

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

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

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

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

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

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

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

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

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

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

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

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

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

[categories]   , ,

|


  09:24 AM

"Fewer your words": advice, not fetish

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[categories]   ,

|


  05:32 PM

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

 

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

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

 

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

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

 

casing. I found this text:

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

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

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

 

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

Outcome: We decided to recommend using We recommend instead.

 

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

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

 

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

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

 

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

Outcome: stet.

 

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

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

[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 (like "the throttle") might not be acceptable in that same auto's owner's manual ("the gas pedal").

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. If you're reading a document that use the verb to trial, is that okay? If the document is about medical trials, there's a good chance that it is. 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]  

[1] |


  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, empirical data that editors can point to to support what experience and insight tells them is true. But sometimes there is, and just this week I ran across something that underscores the editorial push toward consistency, and I was pretty excited about it.

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


Heat map from eye-tracking study (source).

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

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

So what did they learn? A couple of things:

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

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

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

[categories]   ,

|