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.

I get to celebrate a handful of anniversaries today, this month, and this summer, and I thought I'd reflect on them.

Today

Back in February (my birthday month), my wife had the ingenious idea of getting me a monthly pass to our local recreation center, which has a pool. They had just tentatively reopened after Covid, and as I discovered, hardly anyone knew they were open. On February 25, I made my first trip to go swimming. This kickstarted a looong-overdue effort to exercise again.

As I've gotten older, I naturally have gotten heavier, but the pandemic era was particularly bad for me. I sat at my desk for two years, basically, and shoved food into my face the whole time. At the beginning of the year—resolution time—my wife asked what I wanted to accomplish. My answer was that I wanted to lose enough weight that I didn't gasp when I tied my shoes. Hence her idea of the swimming pass.

I started tracking my exercise and my weight in order to stay motivated. As the weather got warmer, and as the pool became more and more crowded, I switched my exercise regimen to walking. In the last 6 months, I've swum 45 miles, walked 650 miles, and climbed 13,000 stairs. I've also started playing occasional pickleball and I recently replaced my stolen bike and started riding again.

This was part of my overall ELEM plan: eat less, exercise more. In addition to moving more, I, er, adjusted my diet. I ate less, and I substantially cut down (but didn't eliminate) sugar, rice, pasta, bread, and alcohol.

At the six-month mark, I can say that I achieved my goal. I lost 13% of my body weight and, hey, I can now tie my shoes without gasping.

This month

This month marks my five-year anniversary at Google (or Googleversary, as we say at work, since we Google-ize everything). The time sure went fast, boy howdy.

People often ask how I like working at Google. My answer is that I've enjoyed this job as well as anything I've done in decades. I really do love editing, and I get to edit engineers who are doing interesting, complex, high-impact things for customers. Back when we were still going into the office, we would get into fascinating discussions about all manner of topics, since the editing crew and the folks who sat near us had widely diverse backgrounds. (Well, the humanities is probably overrepresented on the editing team, it's true.)

Doing this type of work under the auspices of a large company has also been great. Unlike the situation at some (many?) companies, we're treated like adults—people who have lives outside of work that we also need to look after. I have appreciated this aspect of Google immensely.

Anyway, I don't want to blather on too much about this phase of my career, because another anniversary is …

This summer

I went into the tech world in the summer of 1982, meaning I've been at it for 40 years this year. I'd been in graduate school and had gotten a summer job working for a company that did [*waves hands*] computer stuff for law firms, using a minicomputer. When I decided to quit grad school in June of 1982, it was easy to move full time into computers.

The timing was fortuitous. The IBM PC had just come out and there was a lot of interest among professionals—like, oh, law firms—in what people could do with these things. The place where I worked got hooked up with a company that made a database product for the PC, and we put together some applications for document tracking and such-like. So I started doing work on the PC. I did training, I did support, I did a bit of coding. It was all new in those days, the demand for computer stuff far outstripped the supply of people who had formal training, so many of us learned on the job. (And pre-internet, I guess I could add.)

I was in my go-go 20s then, and for the next couple of decades I put in very long hours. That first job gave me (and the family) an opportunity to spend a couple of years in the UK. I moved around in the industry—Asymmetrix, Microsoft, Amazon, Tableau, now Google—doing mostly documentation work at different places.

Portrait by my friend Robert

Forty years is a long time to be in any type of work, and I've certainly considered retirement. My financial guy claims I could do it if I wanted. (He and I differ in how rosy our view is of the coming global economic meltdown, haha.) But I have no urgent reason to retire—I like the work, and it seems like I can now do it from almost anywhere on the globe. I still learn new things all the time, which is definitely an upside to working with such smart people. Another plus is that I experience twinges of impostor syndrome only rarely now. :) And to be honest, I worry slightly that retirement would remove me from a stimulating and rewarding environment. For now I'm playing it by ear. Check back in a bit.

Bonus anniversary!

September 1 is also the anniversary of the date on which I arrived in Seattle. I've reflected on that in the past, so I'll just link to an earlier post about that.

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

Our local pool finally reopened recently, so I'm making one of my periodic attempts to get back into swimming. I have long hair, and the last time I went, I thought, you know, I should get a swim cap.

I researched and learned that there is such a thing as a cap for long hair (i.e. fits over a bun, I guess). So yesterday, Sunday, I betook myself to the local shopping center to go to the sports store. I'm always hesitant about the place because they seem to be, as we say at our house, run by children: the average age of the sparse staff seems to be in the low 20s or thereabouts. But it was local and open.

I found the section for swim caps. They had no long-hair swim caps at all, but they did have a normal silicone cap that I thought might do. In fact, they had two identical packages of them. One was priced at $12.99. The other was priced at $9.99.

I found someone who was working there and asked, "Do these seem different to you somehow?" No. So it was odd that they were priced differently, right? "Let me look that up," the employee said, and went to the register to scan the two packages. After the scan, the employee said that yeah, the price was $12.99. Did I want to buy it?

Dear reader, I now ask you to contemplate whether this could have been an opportunity for a customer-service win.

But the opportunity was not seized. Even though I was holding a package in my hand that was clearly labeled $9.99, they were going to charge me $12.99. And it wasn't even exactly what I was looking for.

I went home and ordered what I needed from Amazon. It was less than $9.99 and it was on my doorstep by 9:30 Monday morning.

Now, I can imagine that some employee had been tasked at some point with updating price tags and had just missed this item. And I can imagine that the employee I talked to was not authorized—in fact, perhaps no employee at the store is—to override the price that the computer lists for an item.

I could have sucked it up and paid the extra three dollars for an item that wasn't quite what I wanted. And I could have felt virtuous doing so knowing that I was "supporting local business," although it turns out that this company has over 400 stores spread around the western states.

This is the dilemma of retail businesses. They can't compete directly with online sources on price or selection. But they have to offer something that makes up for this besides simply being local. Good customer service is a possibility. Knowledgeable staff. The instant gratification of walking out of the store with what you went there for.

There's a local hardware store with 7 outlets in the Seattle area that does this right. They compete with Home Depot and Lowe's (often close by), but they are generously staffed with people who know what they're talking about. Most of the stores are big, and although they don't stock as much as a Home Depot, they stock some of the weirder things you might need, and as noted, they have people who can help you find that thing and can then tell you how to use/install/fix/wire/paint it. I will always go to this store first, and I am willing to pay the "local" price, which is often 10–20% higher than what the box stores charge.

So "shop local" can be a good experience. But, as my sports-store experience suggested to me, local is not by itself enough to compete.

What are your thoughts?

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.

Over the last year and some, we didn't dine out, obviously, since we couldn't. Now that we're easing back into more normal life, I've realized that a year away from the lure of going out to eat has changed my thinking about it a bit.

Of course, many restaurants survived by offering take-out food. We got take-out a few times. But I realized that I didn't like this very much. For one thing, the third-party delivery services have been accused of some shady practices. But even if you order directly from the restaurant, it's a suboptimal experience. My summation of the experience of take-out food is this: cook something; leave it sitting for 20 minutes; serve and (probably don't) enjoy. Now I get take-out only if I intend to eat it more or less immediately.

One of the first things that changed was that we cooked more at home. I'm a, dunno, utilitarian cook: I can make a certain number of things, but I don't aspire to fancy cooking. What the enforced time away from restaurants did, though, was to encourage me to work on cooking things I like. For example, I like going out for diner-type breakfast. Over the last year I actively worked on re-creating that food at home. This was a success for me: I've made waffles, hash browns, eggs over easy, French toast, and hash that to me was entirely satisfactory. (I emphasize that I can now cook these things the way that I like them, not that I should work in a diner.) There are also lunch and dinner foods that I feel that I've perfected for my individual taste. (Same caveat.)

Homemade hashbrowns and eggs

This success has made me ponder the purpose of going out to eat. Certainly I (you too?) have paid for pretty indifferent restaurant meals. At this point, I ask myself why I should go out for a breakfast that I can probably do better (same caveat) at home. Should I wait in line on a Sunday morning to eat a mediocre breakfast? Do I really want to go out for another meal of American Mexican food? I'm beginning to wonder.

Then there is the cost. Any sit-down meal is going to cost $18–20 per person and of course can cost many times that. If I go out for dinner with my wife, we can easily be looking at, what, $50 at even a two-$$-sign restaurant, especially if we get drinks. If one or more of the kids come along, multiply that number. It's not that these prices are unreasonable; it's that it adds up. How much per week should I budget to get meals that have a likelihood of being pretty forgettable?

[source]

But dining out is not just about meals that you might or might not be able to make at home. Going out is about third places—not home, not work, but a third place. For example, unlike my parents' generation, we don't "entertain" at home in the way that seemed to be a premise in many 1950s-era cookbooks. If we want to socialize with people, our custom (and I suspect that of many folks) is to meet up for coffee or lunch or a beer. Obviously, socializing over a table—socializing at all—was severely constrained over the last year and some.

Pages from "The Joy of Cooking" (1975) about entertaining

My wife and I also enjoyed taking our laptops to a coffee shop or pub and working or writing. (I wrote many blog posts at an ale house that was within walking distance of our last domicile.)

Did these protocols change over the pandemic time? I have started meeting people again to catch up, and it's the same as before—find a place convenient to both parties, and then have breakfast or a beer or whatever. But I am much more aware now that I'm paying to socialize, so to speak, and I'm maybe a little more resentful when I shell out a hunk of money for something that wasn't very good, the company itself of course excepted. (It's great to see people in person again.)

Based on my limited experience again of working or writing away from home, I know that I still enjoy that. Coffee shops are opening up again to allow people to sit and work; my wife and I spent a couple of pleasant hours at a coffee shop a few Sundays ago plugging away on our respective writing projects.

Back to writing at coffee shops

It would be easy to get back into a habit of going out 4 or 5 times a week to do this. But it's possible that pandemic-time habits have made me rethink all this. Although it will be easy again to think that I'm too tired to make dinner at home and go out, I've gotten out of the habit. I think about whether I'll enjoy it and how much it costs. The same is true for grabbing the laptop and settling at a table somewhere to work. Fortunately, our libraries are opening up again to allow people to sit and work: a third place that doesn't cost anything to use (though the hours are not always convenient).

I don't think we'll change our socializing habits, though; I anticipate that we'll still meet people out in the third place. But the pandemic reset expectations about socializing, I think. We went months without seeing anyone in person, and I'm still okay with limiting face-to-face socializing to just occasionally, maybe a couple of times a month at most. In this regard I think I differ from my wife, who is not as content as I am to have long periods between visits.

I've read a number of articles about how there's pent-up demand for things to get back to how it was in pre-pandemic times. I suspect, though, that for some of us, the forced changes over the last year have done a reset on our expectations and, possibly, on our habits.

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.

• 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.

These are recordings I've made of me playing solo ukulele. Unless otherwise noted, the tunes come from Graded Repertoire for Ukulele: Classical, Volume 1, a book by Jeff Peterson. The arrangements are his.

Johannes Brahms, "Berceuse" (often known as "Brahms's Lullaby")
Recorded September 6, 2021

Matteo Carcassi, "Andantino"
Recorded June 4, 2021

Grieg, "Hall of the Mountain King"
Recorded May 16, 2021

Ferndando Sor, "Study No. 3"

Recorded April 14, 2021

Ferndando Sor, "Study No. 2"

Recorded March 14, 2021

Dionisio Agudao, "Estudio No. 1"

Recorded February 1, 2021