About

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

Read more ...

Blog Search


(Supports AND)

Google Ads

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

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

Mr. Blue (Garrison Keillor)



Navigation





<November 2014>
SMTWTFS
2627282930311
2345678
9101112131415
16171819202122
23242526272829
30123456

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 11/24/2014

Totals
Posts - 2316
Comments - 2504
Hits - 1,686,192

Averages
Entries/day - 0.56
Comments/entry - 1.08
Hits/day - 404

Updated every 30 minutes. Last: 10:38 AM Pacific


  11:20 PM

Being interested in dictionaries is a sort of sign of uber-word-nerd-ness -- what could be considered more word-nerdy than sitting around reading a dictionary? But for those who do, there is no end of amusement. Nancy Friedman has a cool post about dictionaries, which includes a note about some of her favorites. (The Cowboy Dictionary among them, what fun.) One of my favorites is Mrs. Byrne's Dictionary of Unusual, Obscure, and Preposterous Words, or of course the legendary New Hacker's Dictionary, aka the Jargon File. Anu Garg's A.Word.A.Day list, which mines the incredible richness of the English lexicon, has legions of fans.

On the more utilitarian side, we at work have a prescribed list of reference works. For our dictionary, we use the American Heritage Dictionary. Even knowning that the AHD was designed to counter the "permissiveness" of the infamous Webster's Third, I like the AHD a lot.

But as much as I like dictionaries, in the context of work, I hardly ever open one. In fact, I cannot recall when I last used a dictionary at work to ascertain the definition of a term that came up in documentation that we were writing.

Does this seem odd? Well, consider. My writing colleagues and I are (almost) all native speakers of English, all educated to college level. Which is to say, we have a pretty decent mastery of the basic vocabulary of English. Sure, there are many words that we don't know, and I'm sure that between us all, we can find many words that we think we know the definitions of but don't.

So here's the thing: if well-educated native speakers aren't 100% clear on the definition of a word, should we be putting that word into the documentation? It's not whether we, the writing team, can figure out the word -- it's whether our readers know it. And while the majority of our readers are also probably college-educated native speakers, we are also writing for people who read English as a second language.

We're not doing anyone any favors if we use terms that send ESL readers, let alone native speakers, off to the dictionary. People already don't want to read documentation. If we throw terms at them that they have to go look up, is this helping anyone?

Now and again our corporate style guide indirectly acknowledges this. Take the example of to comprise, a term that people often get confused. Sure, you could look it up in the dictionary. Here's what MSTP says:
comprise
Avoid in general, mostly because its meaning is often confused. It means "include" or "contain." Depending on your meaning, use those terms or consist of or make up as appropriate. Do not use comprised of.
In other words, it's not a matter of being technically, dictionary-says-so corrrect. It's a matter of writing to avoid confusion.

Of course, we use a ton of technical vocabulary. But for the most part, we take responsibility for that: if we throw around terms like manifest or boxing or common language runtime (CLR), we'll define the term and give you a glossary that you can use to look things up.[1]

But what we don't do is use the dictionary to verify some fine shade of meaning, or to justify our use of an obscure term, or even to see whether some highly technical term happens to appear in AHD. In any of these situations, if we have to go to the dictionary, so will users. And if they have to, we lose.


[1] A relatively common discussion I get into with the writers is whether a given term is well known. I will often argue that a term should be defined in text; a writer might argue, in effect, that everyone knows that term. This often comes down to audience: can we expect a given audience to understand certain words? The answer isn't always clear.

[categories]   , ,

[2] |