mike's web log

Not long ago I had lunch with one of our technical writers, and she shared some thoughts about what she referred to as “sparkle” edits. We agreed (I believe) that technical documents benefit from developmental edits to help the writer with organization, purpose, and audience. We also agreed that it’s good to get edits for clarity.

But in her view, there was a point of diminishing returns for editing. It’s certainly possible to comb through a document and make sure that every sentence conforms exactly to our style guide. We can scrutinize the text and see how many words we can squeeze out. We can go back over the text again to make sure that every instance of passive voice is justifiable.

The problem is that this level of editorial scrutiny takes time and effort. And not just the editor’s effort; many such edits have to be discussed with the author to make sure (for example) that the meaning isn’t altered.

Is it worthwhile to do all this work to make the doc “sparkle”? The writer observed the following:

We need to get documentation out in a timely fashion. A few days or a week spent polishing up the prose is a few days’ or a week’s delay in getting the text in front of users. It’s also a few days or a week that the writer and editor aren’t working on other text that’s also important. (See also Editing and “meatball surgery.”)

We know that our readers don’t read every word in our documentation (or anyone else’s). Readers have a problem, they search, they skim, and they read only as much as they need to solve (or think they’ve solved) their problem. The Nielsen-Norman Group estimates that people probably read between 20% and 30% of text on a web page. It’s more important to make sure that text is scannable than it is to worry about some infelicitous text here and there.

Much of our documentation has a relatively short lifetime. A tutorial or whitepaper we’re working on right now might be superseded in a year or two. How much additional work do we want to put into something that will have few readers in 18 months?

As I’ve noted before, one of my early writing leads liked to remind us that “We’re not writing literature here!”

In our defense, so to speak, there are some editorial issues that don’t appear to have direct benefit to the writer or to (some) readers. A percentage of our text-focused edits pertain to making text accessible or more inclusive. Some of what we work on helps our global audience and makes text easier to translate.

And I’ll concede that some of these types of edits do indeed look like “sparkle” edits—they don’t seem to make much difference from the writer’s perspective. But as noted, they help in less obvious ways.

Still, I understood the writer’s frustration with “sparkle” edits. However we might define these, the larger issue is that when editing becomes friction in the process, writers start to get frustrated. If they have customers waiting for a document, and if they’re not seeing the benefits of the edits that they have to review, they become unhappy with the whole editorial process. We see this indirectly in that some of our engineer-writers occasionally choose to bypass our process and publish on Medium or some other more blog-like (and more direct) outlet.

It's important for technical editors to realize that they’re part of a larger effort to get information out to users. Of course we want to give the reader the best possible text. But we have to be very careful about spending time on edits that go beyond helping the reader and that become more about editor-facing concerns (“but that’s what it says in the style guide!”). When we’re standing in the path between the writer and the reader, we want to be very sure that the time and effort that we’re putting forth—and asking the writer to put forth—are really worth it.

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

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

Pros of screenshots

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

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

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

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

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

Cons of screenshots

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Advice for using screenshots

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

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

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

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

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

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

  

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

  

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Suppose you're having a party at home with your friends, rocking out to hits of the 90s. There's a knock on the door. Uh-oh, it's the police. What's the issue, officers? We don’t like this music, they say. You should be listening to Classic Rock.

Who are the police to tell you what music you and your friends should listen to, right? Sure, if the music is too loud, that's one thing. If there were, weirdly, some sort of ordinance that made 90s music illegal, ok. But to have the police tell you what sort of music you and your friends "should" be listening to? No.

You might not be surprised to learn that this little parable is about editing. "You" is an author. "Your friends" is the community that the author is writing for. "The police" is an editor.

Editors do enforce rules and guidelines. What they should not do is impose their own taste on a text.

I've been thinking about this because of a Twitter thread that I saw this week. (I mean, I think about this all the time, but I was most recently reminded of it this week.) The exchange went like this:

Here's a transcript of the exchange:

[To be super clear: the other person in this exchange is not an editor, so this is not a professional ding at them. I'm just using this exchange as an opportunity to discuss an issue that does concern editors.]

I asked my original question because the word onboarding is well established in some disciplines, like HR. I see the term constantly at work (software company), and as far as I know everyone in our office understands the word just fine. If you're writing something for an audience of HR professionals, or even for a bunch of corporate drones (like me), onboarding is not only fine, it's the word that those people use.

Editors are of course allowed to have aesthetic preferences about language. Certain terms might strike them as silly or icky just because. I remember a discussion in the 'aughts among editors at work about the word blog, which some people just hated; others hated the word instantiate ("create an instance of"), which is widely used in the programming world. Not long ago, an author and I tried to find a replacement for the odd term outlyingness but ultimately decided that that our workarounds were not an improvement.

But an editor's feelings about a word are not a valid reason alone for making authors change it. As one of our copyediting principles states, "Have a reason for every change." There are a variety of reasons to ask authors not to use a term: the author has not used the term accurately; the term is "bad" jargon; your style guide says not to use it; it's ableist or potentially disrespectful. It's also perfectly legitimate to confer with the author about whether the audience will understand a term like onboarding or instantiate; another copyediting principle is "Know the audience."

But the many reasons to suggest changing a term do not include "because I don't like it." The editor Jonathon Owen summed this up once in a tweet:

(In case you can't see this, it says "It’s our job to make writing clear and effective, but I don’t think it’s necessarily our job to hold the line against changing usage or to defend the language from its own users. That is, nobody hired us to be in charge of the English language.")

Editors do a lot to make text better for readers. There's plenty to do with that task without also trying to be the boss of English.

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, probably involving Python or Bash and one of several ways to run a scheduled task.

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.

• Background
• Create the PowerShell script
• Test the script
• Schedule the backup
• Test the scheduled task

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

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):

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.

3. 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!

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

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

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

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

This product prevents bad actors from hacking your system.

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

We look for overclaiming in any discussion of performance:

Using this product makes your applications three times faster.

We look for it in mentions of costs:

This product reduces your computing costs by 50 percent.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

We're in the business of solving the reader's problems with the least amount of friction. Sure, reducing word count can be part of that strategy. But an unnecessary in order to or allows you to is virtually never the thing that's preventing the reader from finding and using the information they're looking for. As an editor, I am way, way more concerned that a document I'm looking at addresses a real user need, that the reader can find the information as fast as possible, 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.

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.