I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search

(Supports AND)

Google Ads


Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.


As for kissing on the first date, you should never date someone whom you would not wish to kiss immediately.

Mr. Blue (Garrison Keillor)


<April 2021>



Contact Me

Email me

Blog Statistics

First entry - 6/27/2003
Most recent entry - 3/15/2021

Posts - 2634
Comments - 2643
Hits - 2,364,698

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

Updated every 30 minutes. Last: 9:28 AM Pacific

  08:54 AM

The hazards of overclaiming

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

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

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

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

This product prevents bad actors from hacking your system.

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

We look for overclaiming in any discussion of performance:

Using this product makes your applications three times faster.

We look for it in mentions of costs:

This product reduces your computing costs by 50 percent.

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

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

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

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

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

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

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

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

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

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

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

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

[categories]   , ,


  10:40 PM

I did another uke recording (as noted, to keep me on track while practicing). Rather than post separately for each recording, I'll try just keeping a list of the recordings in one post. The most recent recording is at the top.

Ferndando Sor, "Study No. 3", arranged by Jeff Peterson

Recorded April 14, 2021

Ferndando Sor, "Study No. 2", arranged by Jeff Peterson

Recorded March 14, 2021

Dionisio Agudao, "Estudio No. 1", arranged by Jeff Peterson

Recorded February 1, 2021

[categories]   ,


  04:22 PM

I've been working from the book Graded Repertoire for Classical Ukulele with arrangements by Jeff Peterson. I'm plugging away at learning to translate written music to ukulele strings and learning some basic techniques from classical guitar as applied to the ukulele.

Update I decided to make a single blog entry that tracks these recordings. (The link to this recording is repeated there.)

I could practice the same pieces forever, probably. So I thought I'd finish them as you do when you take piano lessons: perform them. In my case, I thought I'd record the pieces I really liked, and then declare myself done with those pieces. This is my first effort, "Estudio No. 1" by Dionisio Aguado (1784-1849), arranged for uke, as noted, by Jeff Peterson. This is the 4th piece in Grade 1 (of 8), and has been my favorite so far.

Estudio No. 1

[categories]   ,


  09:56 PM

On the ukulele (as with guitar), the idea of movable chords is that the shapes you learn for open chords constitute patterns. By adding a barre, you can move the shapes up the fretboard to form new chords. For example, you can take the C shape, move it up 2 frets, and get a D:

If this is a new concept for you, may I recommend my booklet on movable shapes for ukulele (PDF).

In this post I want to talk about the patterns—the relationships—for moving these patterns around the fretboard. Bear with me while I explain this notion.

On the concert uke, there are basically 5 shapes for playing movable major chords[1]:

In addition to making it easy for you to move a C shape to a D shape (for example), this means that there are 5 ways to play any given major chord. Here are 5 ways to play a C major chord:

There's a relationship—a kind of circle—among these shapes in terms of how you can move between these different ways to play the same chord. I'll show you the diagram and then illustrate how it works.

Here's a different, more formula-like way to indicate the same thing:

C shape + 3 frets = A shape
A shape + 2 frets = G shape
G shape + 2 frets = F shape
F shape + 3 frets = D shape
D shape + 2 frets = C shape

What does all of this mean? It means that when you play a major chord using a movable shape—any major chord, any movable shape—you can easily figure out how to play the same chord using the other shapes.

I'll start by illustrating this using the C shape:

Per the diagram/formula earlier, we can make another C chord by taking the open C shape, moving up 3 frets (C shape + 3 frets), and making an A shape:

Following the formula, to make another C chord, we can move up 2 more frets and make a G shape (A shape + 2 frets = G shape):

Keep going. If you're making a C using the G shape, the next C chord is 2 frets up and using the F shape:

Move the F shape up 3 frets and make a D shape, and you've got yet another C chord:

Finally, move the D shape up 2 more frets and you've back to the original C shape:

I say that this pattern is circular because you can wrap around, so to speak. Start anywhere in the circle to make a shape. Move up or down the designated number of frets, make the next shape, and you've got the same chord. For example, here's a sequence of A chords starting on the open A shape. Notice that the intervals (number of frets) between each of the shapes follows the diagram/formula from earlier:

The pattern is also circular because you can move backward, i.e., down the fretboard the designated number of frets. For example, if you're making an A chord on the 7th fret using the D shape, you can make an A chord move down 3 frets to the 4th fret and switch to the F shape. (D shape minus 3 frets = F shape)

A couple of additional notes:

  • For purposes of this exercise, open chords are fret 0 (zero). For example, if you make an open A chord and want to make the same chord in the G shape, the formula says to move up 2 frets. Zero plus 2 is 2, so barre the second fret.
  • Fret 12 is the equivalent of fret 0—in other words, any chord that you make by barring fret 12 is the same as the open chord. If you get to the point where the numbers take you to fret 12, just go back to an open shape.
  • There are similar circular patterns for other chords—minor, 7ths, etc. I'll put those together in the fullness of time. Teaser: the patterns—the number of frets between chords—is the same for minor chords as for major chords; in other words, you already have the circular pattern for minor chords.

And finally, why is it useful to know this thing? Obviously, you don't sit around moving from shape to shape for any given chord when you're playing.

For me, this has helped a bit as I try to visualize where the chords are on the fretboard. When I initially started with movable chords, it felt a bit like they were just scattered around on the fretboard. ("I know there's a C chord in an A shape, but where is it?") I could look them up in the "dictionary" of the movable chords booklet, but as I worked with the shapes it became clear that there were patterns to how the different fingerings for the same chord were related. So I just sat down and worked it out.

I think this is probably an interim measure for learning out the locations of chords. I imagine that after many, many, many hours of practice, you just know where the several C chords are, and the A chords, and the G chords, and so on, and you don't have to calculate it. In the meantime, I keep a sticky note on my music stand with this major chord circle.

[1] As I note in the booklet, there are also 3-string chords and occasionally some open chords that it isn't practical to move because they're just too darned awkward to barre. I'm sticking here with a basic theory of movable chords.

[categories]   , ,


  10:16 PM

Every year I get out the trusty Hal Leonard Christmas Carols for Solo Ukulele book and see if I can remember the ones I learned the year before and maybe learn a new one. Then I use my primitive home recording setup to record them, just for fun.

Here are recordings of some of them that I made this year. These are all MP3 files that are about a minute long and all less than 1 MB.

PS I'm not a very good uke player.

Note: For technical reasons that I don't understand, you might have to refresh the page after listening to a track before you can listen to a different track. Sorry :(

Away in a Manger

Jingle Bells

O Tannenbaum

Silent Night

Merry Christmas!

[categories]   ,


  10:26 PM

Covid and name-spelling

I've always had an issue in trying to tell people what my last name is. As I've written about before, people have a hard time understanding the name Pope. "Hope?" "Polk"? There's just something about that combination of consonants that's always hard to hear, especially over the phone.

Well, Covid certainly hasn't helped. I'm not a particularly clear talker under the best of circumstances. Add to that wearing a mask and talking through a plastic shield, and I feel like I practically have to yell to transact business when I'm at a store. One of the local shops posted the following sign, which might seem vaguely rude, but I think everyone understands the issue.

However, even yelling is often not enough to make my name clear to people across the counter. For some people, it can help to spell their name. But the letters P-O-P-E sound similar to other letters, like B, D, E, and spelling my name can just generate a second round of "did you mean …"? Another option is to say something like P as in Peter, and so on. When I talk on the phone with people who are accustomed to the problems of transcribing names, they'll sometimes do this.

Long ago the military solved this problem by inventing a so-called spelling or phonetic alphabet. You probably know this alphabet, which starts with Alfa (or Alpha), Bravo, Charlie, and finishes with Yankee, Zulu:

The beauty of this particular alphabet is that the names were carefully chosen to be unambiguous. Although the letters B and P sound similar, the words Bravo and Papa don't, so there's not much chance of them being confused, or Delta and Golf, or Mike and November. If you look through this alphabet, you'll see that none of the names sound like any of the other names.

So now when I am masked up and talking through a shield, I've taken to preemptively spelling out my name using this alphabet. I'll go to the pharmacy, and when they ask what name the prescription is under, I'll say "POPE, Papa-Oscar-Papa-Echo!" I sometimes get funny looks after this, but so far, no one has misunderstood what I'm spelling out.[1]

[1] Many people who were in the military know this alphabet, and a guy I used to work with who was ex-military taught me the term Charlie Foxtrot as a way in polite company to refer to a clusterfuck.

[categories]   ,


  10:52 AM

Over the weekend I ran a security check on my computer. One of the startling results was the report by my password manager that I had many dozens of "compromised passwords."

After my pulse returned to something resembling normal, I looked a little more closely at the report. What they were not saying, I had to figure out, was that dozens of my accounts had been compromised. They only meant that the password that my password manager is storing for some websites was among the passwords found in someone's data breach.

I looked through the list of affected websites in my password manager and had an Aha! moment: virtually all of them are sites where I use a "throwaway" password. That is, I'm interacting with a site and they insist that I create an account, and I end up using the same password over and over. For example, I've done this for some sites that I intend to visit only once.

This is a bad idea, and I should know better. Reusing passwords is a big security risk.

Think about how this works: you use the same username and your throwaway password for a number of sites. One of the sites is breached, and your password and username fall into the hands of people with mal intent. These people then try your username+password combination on hundreds or thousands of sites. In my case, for example, they could have gotten access to dozens of sites that way.

I like to think that I've reused my throwaway password benignly, only for "unimportant" sites. But I can see in retrospect that even if the sites have no commercial value, someone could impersonate me on those sites and do some sort of mischief.

But I think we can also imagine many people using the same password not just for benign sites, but for important sites. This is one way that people's social media accounts get hacked.

So, in part for my own benefit, let's review some security practices that everyone (me, too) should be following:

Don't use the same password on different sites. As explained earlier.

Use a strong password. A strong password is one that's long and random. It doesn't mean just substituting numbers or punctuation in a word (like S3att!e). A decent approach is to use a passphrase rather than password: not just a string of characters, but a string of words. The longer the phrase, the more "entropy" it was, meaning that it's harder to crack. Many people know the xkcd cartoon that explained this beautifully:

Of course, the site has to allow this. A surprising number of sites still prohibit spaces or have a too-short maximum password length. And the "strong test" that some sites show you as you're creating a password isn't necessarily very good, so don't take their word for it.

Use a password manager. One reason people reuse passwords is so they can remember them. Use strong passwords, as noted, and then let a password manager do the remembering. You just have to remember one password, namely the one for the password manager. (Use a strong password for that, please.)

If a site offers it, use two-factor authentication. Two-factor authentication (2FA) is where you have to provide both a username+password and a one-time password (OTP) that they send you in email or text message. 2FA isn't perfect, but it's better than username+password alone.

Among 2FA options, a good one is a hardware key, like those offered by Yubico. For this, you have a little thing that looks like a USB dongle; as part of your login, you have to touch the key. Hardware keys aren't supported on many sites yet, but you can use them on some important ones, including Gmail. (Full disclosure: we use hardware keys at work.)

Use security questions wisely. In 2008, Sarah Palin was famously hacked by someone who got answers to her security questions by studying her biographical data. The answers to your security questions are probably not that hard to find either—for example, how fast do you think someone can discover your mother's maiden name or your high school mascot? (Many social-media questions and polls seem designed to solicit information that can be used to answer security questions.)

If a site insists that you have to set up security questions, you can create answers that are meaningful to you but that aren't easily guessable. As the simplest possible approach, just lie. Just remember what your lies are. :) A more sophisticated approach is to devise an algorithm for yourself that you always use. For example, maybe you take the first letters of the question and use those as an answer. If the question is "What is your mother's maiden name?," your answer could be WIYMMN. (Don't use this particular algorithm, please.) Or you do something with numbers or whatever. The idea is just to have something that you can reproduce many months hence but that isn't guessable.

Get rid of accounts you're not using. Did you set up an account on Pinterest or Coursera or the Los Angeles Times but you never use it? Delete the account. No password worries then for that account.

And finally, lock down your main email account as tightly as possible. When there are changes to your accounts, like a password change, you often have to confirm them via email. But if your email account has already been compromised, the game is up.

I guess I'll also note that I don't let websites store my credit card number. The only company I really trust is Amazon, in part because during my time there, I was impressed with the level of paranoia that they have about security issues, haha. But if J. Random Website offers to store my credit card info, no thanks.

If you want more details on all of this, I highly recommend a whitepaper written by a couple of the solutions architects at work: Modern password security for users (PDF). They have great ideas about strong passwords, about how to handle security questions, etc.



  12:19 PM

In an effort to improve my sleep regimen, I was recently prescribed a CPAP machine. This device helps with obstructive sleep apnea, where your throat closes during sleep. The CPAP machine basically pushes air into your nose and/or mouth to keep things open.

The concept is relatively simple, but it involves technology. You wear a mask; the mask is connected via a hose to the device itself, which blows air and has sensors to adjust the pressure and temperature. There's a water reservoir so the machine can humidify the air it's blowing at you. There are air filters that need to be changed periodically. The mask, hose, and water reservoirs need to be washed regularly.

So how does the manufacturer (Philips) make and distribute a machine that's a this complex but is intended for a wide variety of people? I count four ways, and am wondering about a fifth.

First, before you can take home your CPAP machine, you get a 20-minute training session slash demo. The trainer walks you how to assemble and use the machine, and they give you the schedule and some tips for cleaning.

I read once that people retain 10% of what they hear during a presentation. The exact number (10%) isn't that important; the idea is just that people don't retain everything you tell them.[1] And I think about all the people who use a CPAP machine. Is a 20-minute demo going to be enough to train this wide range of people? My guess is no.

So second, the machine comes with a manual—two, in fact, a quickstart and a detailed manual. These reiterate a lot of what you learn in the presentation, so you have at least the possibility of hearing it all twice. The quickstart has a lot of pictures. (The manual, a few line drawings.) For me, it was an interesting case of reading documentation for something that I felt I kind of already knew but that I needed some refreshing on.

A third way that Philips tries to help their users is through design. For example, when things connect, they go together in only one way. There's only one way to plug in the machine. The hose goes into the machine only one way. The filters and water reservoir go into the machine only one way; you can't close it if they're not right. The nosepiece in the mask has clear markings right on it for how to put it together. These are all versions of self-documenting features: you literally do not need to read the manual to understand how to put together the components.

As another example, there are very few controls on the machine. For basic use, you need to press only a single button to turn the machine on and the same button again to turn it off. There's a second button if you want to adjust the "ramp"—that is, to set the air pressure to increase gradually when you start up the machine.[2]

And there is a fourth way in which Philips can help people. The machine phones home to report a bunch of statistics about the user's sleep. (That part of the machine required no setup at all, which was great.) This feature has several purposes (some of them a little uncomfortable to contemplate), but at least if the distributor is getting odd reports or no reports from the patient, they know something went wrong. Perhaps they contact you if that's the case.

I imagine that with these efforts on Philips's part, most people can manage to put on their mask and get the machine running. But how well Philips does attempt to help users with ongoing maintenance? It's easy to forget to fill the reservoir. Similarly, the training emphasized that you should wash the hose every week. Is everyone really going to do that? I mean, we're all supposed to floss every day, but how many people really do that?

So I wonder. Does the machine stop and display a message if the water reservoir is empty? Does it tell you when it's time to change an air filter? Does it (somehow) figure out that it's time to wash the hose? I don't know, and I'm reluctant to get into a situation where the machine has to tell me these things. But given the many ways in which the machine, once running, can go wrong, I hope that the manufacturer has taken steps to try to keep it going.

All in all, giving out a complex piece of technology to people and expecting them to all use it right is a hard problem. It's clear that the folks at Philips have thought a lot about this and come up with different ways to try to handle it. Still, I am curious how many people fail when trying to use the machine—they never figure out how to use it, they use it wrong, or they don't maintain it and the machine itself fails. As someone with a professional interest in communicating complex concepts, I find this to be an interesting challenge.

[1] Someone on my team at work has a variant on this idea: you need to hear something 7 times before you learn it. ^

[2] There is also a dial that you can use to make a bunch of other settings, and the dial is multi-modal: turn left for one mode, turn right for another mode, and push for a third mode. Arg. I hate multi-modal controls. But at least this one is optional after you've done the initial setup. ^

[categories]   ,

[1] |

  12:16 PM

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

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

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

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

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

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

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

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

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

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

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

[categories]   ,


  08:15 PM

I spend a lot of time on social media—Facebook, Twitter, and Instagram. There's value here; for example, I "know" many people only through these media, and I much appreciate what I've learned from them. For example, I know hardly any linguists IRL, but I follow many on Twitter, and it's great.

But even I can tell that I overdo it. It's a time suck, and it's an easy way to procrastinate when I need to be doing, you know, work. ("While this documentation is building, I'll just check Twitter quick-like.")

More insidiously, too much social media starts making me cranky. And when I get cranky, I do unfortunate things, like respond in pissy ways to innocent posts by other, nicer people. Or, gah, I give in to the temptation to respond to morons and their idiotic political opinions, a no-win situation if ever there was one.

So I decided recently to implement what I'm calling Asocial Sundays. Between midnight on Saturday night and midnight on Sunday night, I don't visit any social media sites, period.

This is a new experiment, but I can see some benefits already. Not having the option of social media redirects my attention to more productive things. If I'm sitting at my desk and finish some task—paying bills, say—I don't just mindlessly switch to FB or Twitter to see what's up. Instead, I might actually get up from my desk and wander into the rest of the apartment.

It also has been a way to unplug from a source of stress. We all know that it is distinctly not conducive to good sleep to doomscroll Twitter before bed. Politics and COVID are inescapable on social media, and both are not only inherently stressful, they're sources of endless arguments, outrage, scolding, shaming, uninformed opinions, and on and on. It's nice to take a break from that.

I'm far from ready to withdraw altogether from social media, the way some of my friends have. (A social media detox or social media fast, as it's sometimes called.) I've occasionally considered unplugging permanently from Facebook because their ad models are scary and because Zuckerberg is an incorrigible weasel. But as I say, I still get a lot from my social interactions.

If the experiment goes well, I might at least expand my lights-out policy for social media. I suspect that the more I do it, the easier it will be to use social media in a healthier way.

[categories]   ,