mike's web log

"Sparkle" edits

Tue, 21 Feb 2023 19:03:56 GMT

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

To screenshot or not to screenshot?

Sun, 10 Apr 2022 21:38:09 GMT

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

Why random formatting isn't a good idea

Mon, 13 Sep 2021 15:22:09 GMT

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.

[more]

We are not the boss of English

Mon, 30 Aug 2021 10:57:41 GMT

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:

Them: What's a better, less annoying jargon-y word for onboarding?
Me: Are you looking for a different term because you don't like it or because the audience isn't familiar with the term?
Them: I despise the word.
Me: But if it's a term used by your readers—?
Them: I'm trying to teach them a better way.

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

Automatically backing up the Normal.dotm file

Mon, 26 Apr 2021 21:32:32 GMT

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

The hazards of overclaiming

Mon, 15 Mar 2021 08:54:25 GMT
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.

[more]

More dubious guidance, reclining edition

Mon, 27 Jul 2020 12:16:57 GMT

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.

[more]

A beef with cloud metaphors

Sat, 04 Jul 2020 10:42:28 GMT

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

"Fewer your words": advice, not fetish

Mon, 13 Apr 2020 09:24:02 GMT
"Fewer your words": advice, not fetish
A couple of weeks ago, a (virtual) discussion broke out among the writers at work about "empty words" and how these should be eliminated. The original posting was about removing phrases like allows you to, helps you to, is intended for, and some others.

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

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

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

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

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

For that matter, the original assertion that phrases like allows you to, helps you to, and [more]

Good & bad jargon: some real-world examples

Thu, 26 Mar 2020 17:32:14 GMT

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

Good jargon and bad jargon

Tue, 24 Mar 2020 08:15:14 GMT

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

What's "good" jargon?

Audience

What's "bad" jargon?

How can you tell good from bad jargon?

But that's a terrible term!

However …

It's not easy

What's "good" jargon?

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

macula and percutaneous transluminal coronary angioplasty (medicine)

commoditization and Gini coefficient (economics)

affinitization and instantiation (computer programming)

em dash and down style (editing)

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

[more]

Readability and pharma instructions

Mon, 06 Jan 2020 07:09:52 GMT

My life has been blessedly free of the need for pharmacological intervention, but I recently went for a checkup and left with a fistful of prescriptions. Because this routine drug-taking was sort of new to me, I actually read the inserts that came with the several prescriptions because, well, perhaps there was something I needed to know.

The text was hard for me to read, but that was only because it was in such small print—8 points, perhaps less. And there was quite a lot of it. But this technological limitation at aside, I was surprised at how readable the words themselves proved to be. Perhaps—and this is my observation—by design?

Some details. There are about 1230 words in all, which is about two and a half pages. The text is printed in blobs, aka “walls of text.” The only formatting is ALL CAPS and ALL CAPS IN BOLD. The text is not laid out with an eye to scannability. You can get an idea from the following, with a US quarter coin (about 1 inch/24 mm) for scale.

But as I read the text, I noticed that it seems written for clarity. Here’s an example:

Use this drug as ordered by your doctor. Read all information given to you. Follow all instructions closely. Take this drug at the same time of day. Take with or without food. Keep taking this drug as you have been told by your doctor or other health care provider, even if you feel well.

I noticed these things:

Sentences are short.

Words are (for the most part) simple and direct.

Instructions are clear and are written as imperatives.

The text anticipates possible reader questions (“… even if you feel well”).

[more]

Editing and "meatball surgery"

Mon, 29 Apr 2019 12:07:04 GMT

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

Warning Potentially distasteful content—surgery, unpleasant metaphors.

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

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

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

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

[more]

Science supports editing guidelines, yay

Mon, 16 Jul 2018 22:00:54 GMT

There are a variety of editorial truisms: long sentences are hard to read; lists should be parallel; consistency is good. This wisdom is taught, and it's reinforced by personal experience; editors are themselves readers, after all, and they monitor their own reactions when reading.

However, there isn't always hard, empirical data that editors can point to to support what experience and insight tells them is true. But sometimes there is, and just this week I ran across something that underscores the editorial push toward consistency, and I was pretty excited about it.

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

Heat map from eye-tracking study (source).

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

[more]

More dubious guidance

Tue, 22 May 2018 09:37:21 GMT

I know how this happens, I do. A tech writer is given a task to "document the product," and it turns out there isn't much to say. But telling the bosses that nope, it's ok, we don't actually need to say anything about this might be perceived as, dunno, not being cooperative. Maybe even suggesting that the writer's job isn't that important.

Anyway, today we have a couple of examples of what might result if the writer (and common sense) does not prevail. First up, we have these, um, helpful instructions that came with a compass that I own:

There must be a universe in which people buy compasses who don't already know what N, E, S, and W mean. I don't believe we live in that universe.

But even that is reasonable compared to the following, which Twitter user Alex Warren posted today:

Better keep this for future reference in case I forget what each button does pic.twitter.com/UO795hO3Xn
— Alex Warren (@alexwarren) May 22, 2018

More dubious guidance: 1, 2, 3, 4, 5 [more]

Signposting in documentation

Mon, 15 Jan 2018 21:46:18 GMT
Suppose you're on vacation and you're driving to a place named Lisbon Falls. You see this sign, so you turn right.

[Source]

After you turn, you drive for a long time, but you don't see Lisbon Falls, and you start to doubt that you're on the right road. How helpful would it be to see a sign that said "Lisbon Falls—keep going "?

Obviously, we need signposts to tell us where to turn. But sometimes we need signposts to reassure us that we're going the right way. Since I work in documentation, I'm going to talk about this applies when you're writing instructions.

The first and least controversial example is to show the results of the user's action, like this:

This type of signpost reassures the reader that they've run the command correctly, or made the right gestures in the page, or whatever.

A second type of signpost is one that makes sure the reader is properly oriented at the beginning of a procedure. This comes up a lot in the complex tutorials I work with, which might have many separate procedures. What I tell my writers is that at the beginning of each procedure, they should make sure that the user is clear about where they are. Here's an example:

[more]

MS Word: avoiding taboo words and other tricky vocab

Wed, 05 Jul 2017 15:02:05 GMT
As most people discover, there's a class of writing error that spell check just can't help you with. Consider these examples:
We recommend that the company shit its resources for better output.
The event is open to the pubic.
Run these through spell check, and all is well. Only, of course, it's not.

As I recently learned, Word has a feature that can help find errors like this: an exclusion list. An exclusion list has words that are spelled perfectly fine, but that should be excluded from your documents.

The steps for creating an exclusion list are described in a great blog post by Sam Hartburn. The basic idea is that you add words, one per line, to .lex files in a specific folder on your computer. Here's the Windows location--see notes later for Mac instructions:

You can use any text editor to edit the file, including Notepad.

Note that there are different .lex files for different languages, and in fact for different flavors of each language—e.g. English US and English GB. (It's not inconceivable that there's a way to set up a global .lex file, but I don't know. Leave a comment if you know about that.)

Once you've got your exclusion list(s) updated, close and then reopen Word. Then when you run the spell checker, Word will flag words that are part of your exclusion list:

The examples I've shown here pertain to, you know, taboo vocabulary. Another excellent use for this feature is to flag words that you often mistype but are technically spelled correctly, such as [more]

Congratulations on your success

Thu, 15 Jun 2017 16:14:36 GMT
On Facebook today, one of the editors I know, Amy J. Schneider, posted about a habit that some writers have, namely adding a kind of reflexive "successfully" to their sentences. Here's an example, which I'm sure we've all seen variations of:

You haven't just logged off. You successfully logged off. (Thankfully, you didn't unsuccessfully log off.)

I see this all the time, and it bugs me pretty much every time. Just for yucks, I did a search for "successfully" in the documentation set I’m currently working on. I found 1473 instances; here are just a few:
Snapshot created successfully.
Successfully logged into database.
After you have successfully created the file, …
Click the Check button to verity that the service can successfully connect to your job.
To confirm that the volume was successfully taken offline, …
After the device is successfully updated, it restarts.
Make sure the test has successfully passed before you proceed.
… and on and on and on.

I ask you: is the word successfully really necessary in any of these instances? I posit that it is not. Moreover, and since I apparently am dispositionally incapable of not doing this, I ask myself "Wait, is there an unsuccessful way for this to happen?"

I reckon I could do a global search-and-~~destroy~~ [more]

Bang!

Tue, 13 Jun 2017 12:23:17 GMT
The linguist Geoff Nunberg has an essay on NPR today in which he tells of his rediscovery of the joys of using exclamation points. As he notes …
Yet writers and editors only pride themselves on expunging the marks, never on sticking them in. When it comes to exclamation points, the only virtue we recognize is self-restraint
This is true. In my work (software documentation), we maintain a tone that is, while not entirely academic, pretty neutral. Just the facts. And facts rarely require exclamation marks.

A story I've told many times: Years (decades) ago when I was learning the craft, I drafted something in which I'd included an exclamation point. My then-manager circled it and added this note: "Nix. Too exciting." I've added very few exclamation marks since then.

Technical docs have been on a path toward more friendliness, it's true. And these days especially, docs might initially be created by people who do not spend their days in the tech-writing trenches. The result is that some of these drafts can have a distinctly marketing feel to them, which of course includes exclamation points. Which I always take out.

And more than one exclamation point? Good lord. From the editor Andy Hollandbeck I learned the word bangorrhea, which is the use of excessive!!! exclamation points. The developer Rory Blyth once summed up this editorial attitude: "The use of more than one exclamation point side-by-side, in any context (except comics), is a sign of mental insanity, a marketing degree from the University of Phoenix Online, or both."

[more]

Things I learned from my presentation feedback

Tue, 17 May 2016 08:23:20 GMT
At the end of March I gave a presentation at the ACES conference on "Tips and Tricks for Using Microsoft Word Styles." For years I've taught a class about Word styles at Bellevue College. My experience is that even people who use Word don't necessarily know all the ins and outs of using styles, so when the call for papers for the conference came out, I submitted a proposal. It was accepted, and I was given a 60-minute slot.

I spent a lot of time preparing for the session, agonizing about what material to include. Much of my indecision was because I simply didn't know who my audience would be. Would there be people new to styles? Were all of my tips already old hat to an audience of experienced editors? Plus I only had an hour, which I know from experience seems like a lot of time, but is nothing. (My course at BC runs 6 hours.)

I ended up presenting a quick overview, and then a lightning tour of how to apply, create, and manage styles. Along the way I threw in tips that I reckoned could be useful to even people who had worked with styles: keyboard shortcuts; tips for naming styles; style inheritance; styling TOCs; taming multi-level list styles; and more. There were about 60 people in the room.

Presenting about styles. (Photo: Lindsay Lelivelt)

I got the evaluations back recently. There was enough positive feedback to suggest that yes, it was a useful session and that people got good information from it. Big relief! A number of commenters indicated that they liked "technical" sessions, which I hope means I'll have another shot at a session like this.

[more]

Light(e)ning fast

Tue, 05 Apr 2016 19:38:19 GMT
I was editing something at work today and ran across the phrase lightening fast, with bonus e. This got my attention—I've seen this spelling plenty, but it was an unusual context. So I got to thinking about this spelling and why using lightening for lightning isn't all that unreasonable.

First, it's not uncommon. Using the phrase bolt of lightening as a way to search for the term, I found 10 instances in the COCA corpus versus 206 instances of bolt of lightning. Let's call that a 4–5% hit rate. Thunder and lightning gets 156 hits; thunder and lightening gets 5, which is a somewhat lower incidence of around 3%. But it ain't zero. Point is, people do use the lightening spelling; not a lot, but it's out there in printed materials.

Second, it's not an error that spell checkers can find. Lightening is a perfectly cromulent word in its meaning of "to make or get lighter," as in lightening one's load. It's possible that a grammar checker will find the error; for example, if you write "bolt of lightening," Microsoft Word's grammar checker flags it. But in most contexts, grammar checking is not available.

Finally, it can make sense from a phonological perspective. Unless one's pronunciation is particularly precise, it's not hard to hear or make a vowel between the t and n in lightening. This is a phenomenon known as epenthesis, which is common in many dialects (mason-a-ry, [more]

The "born" supremacy

Tue, 16 Feb 2016 21:17:18 GMT
I was reading an article today about Zika, the viral disease that's causing microcephaly in Latin America. Tragic. But I was taken by a language aspect to the article. At one point, the author writes:
Less pesticide means [...] more mosquito-born diseases.
This spelling appears twice in the article, so it seems to be deliberate. There are a couple of possibilities here, I think.

One possibility is that the writer intends borne, but doesn't know how to spell it. This isn't surprising; they're homophones, after all, and born is anywhere from 20 to 50 times more common than borne, depending on which corpus you examine.

Another possibility is that the writer doesn't realize that he really means borne, i.e., the past tense of bear (mosquito-borne disaease == mosquitos bear [carry] the disease). In that case, mosquito-born is an eggcorn: an error, but one that sort of makes sense, since the disease might be "born of" mosquitos.

In edited text it doesn't show up very much. For example, the COCA database lists only one instance of mosquito-born versus 92 instances of mosquito-borne. But a Google search [more]

Is this a typo in the New Yorker?

Sat, 13 Feb 2016 13:56:50 GMT
I hesitate to call "typo!" here, but I did find something odd in the February 1, 2016 issue of The New Yorker (page 45):

In case you can't read it, this is the text, with the oddball term highlighted:

Sarah Palin, the pre-Trump embodiment of populist no-nothingism in the Republican party [...]

I would have expected here the name know-nothingism, which I would have understood as a reference to the Know Nothing movement of the 1850s, which had a strongly nativist bent, and which I assume the author of the NYer article, Ryan Lizza, intended to invoke.

I'm wary of this conclusion, tho, because the NYer is about as rigorously edited a publication as there is in the U.S. today, and it would be surprising, to say the least, to find a typo like this.

What am I missing here?

More on ambigious "should"

Tue, 12 Jan 2016 09:04:43 GMT
I was reading a thread on a computer forum, and someone asked this question:
Quote:
Your password should contain at least 6 characters

If you're going to require it; don't say "should", say "must".
This set off an interesting discussion on the semantics of should in this context. I've written about this before, so I was interested to hear how people interpreted the example.

Here is a sampling of the more serious posts on the thread:

From the requirements document: "The password entered by the user should be rejected if it does not contain at least six characters." If I received that requirement from my boss, I would make darn sure that the password is rejected. I don't think I would randomly reject some and not others.

The software is being polite; it's anticipating users who do not like being told what to do.

If it says "should" then it is not optional, like in "could". You should be "this tall" to ride this ride.

A number of people pulled out dictionary definitions (Wikitionary, heh). And one person cited RFC 2119 ("Key words for use in RFCs to Indicate Requirement Levels"), which states:

MUST This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.

[more]

We'd better document that

Mon, 03 Aug 2015 21:54:24 GMT
From my daughter, another example of poor design patched by documentation.

Who imagined that a) having an unlabeled numeric scale was a good idea, and b) you move the knob to the right for "colder"?

Let's at least fix the first problem, shall we? Like this:

We can't use documentation to fix the problem of having to dial "more cold." But at least we don't to print a frickin' manual right on the freezer.

Update 4 Aug 2015 In response to Hal's comment, here's an improved design that even has redundancy for those who aren't sensitive to color differences.