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 a college instructor, I am long past thinking that students will heed my advice. God knows I've tried. So with each new class I limit myself to one saying, the most useful one I know: "Eighty percent of success is showing up." What most students don't know is that showing up will be the hardest part about college.

Brian Burrell



Navigation





<September 2017>
SMTWTFS
272829303112
3456789
10111213141516
17181920212223
24252627282930
1234567

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  
  RSS  
  RSS  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 9/19/2017

Totals
Posts - 2452
Comments - 2558
Hits - 1,983,775

Averages
Entries/day - 0.47
Comments/entry - 1.04
Hits/day - 382

Updated every 30 minutes. Last: 7:29 PM Pacific


  03:02 PM

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 manger for manager or potion for portion. Or you can use it for terms that should be avoided in your particular work, even if they're perfectly cromulent words in English. Really, you can use the exclusion list feature to have Word bring to your attention any word that you might want to double-check as part of your proofing.[1]

I do have a couple of notes for you about using exclusion lists:
  • Words in the list are case sensitive. (As indeed they are in the Word spelling dictionaries.) For example, it's probably a good idea to include both assed and Assed.

  • It's up to you to include all variant forms of a term, including plurals and verb conjugations: ass, Ass, asses, Asses, assed, Assed, assing, Assing, etc.

  • With regard to having different .lex files for different language variants, it will up to you to know what languages are in use in a given document. If a document has been through many hands, it's possible that different sections or paragraphs or even words might be flagged as having different language settings.
I learned about all this from a Twitter thread and specifically from the editor Ashley Bischoff. Not only did she introduce a bunch of us to exclusion lists by pointing to the blog post, she took the initiative to create a Google Docs spreadsheet for collecting words for potential inclusion. The doc is open to anyone. Please contribute!

PS Ashley has a second sheet in the workbook with instructions for both Windows and Mac users on how to update your exclusion lists.


[1] Microsoft alums will recognize this as similar to the Policheck tool, about which I've written before.

[categories]   , ,

[2] |


  04:14 PM

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-destroyreplace on "successfully" in our documentation set without worrying that I would be changing the meaning of anything. (I'm not actually going to do this, just to be clear.) In fact, I'd be shaving nearly 20,000 characters out of the docs. Which is to say—of course—that I'd be shaving those characters successfully.

[categories]   ,

|


  12:23 PM

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

Still. Nunberg points out that exclamation points have discursive purpose in informal writing, "chiefly to signal friendliness." If I examine my emailing habits, I have to admit that I do use them like that. To me there's a pretty obvious difference between signing off an email with

Thanks,

versus

Thanks!

… for example.

And I've also noticed that I use an exclamation-mark-based way to indicate a kind of written eyebrow-raised-in-surprise. Like this:

They said they'd be here at 8:00 am (!)

Apparently over 50 people (!) have accepted the invitation

I'm not sure where I picked up this tic or how widespread it is. But I'm not sure how'd I'd replace it if for some reason I could no longer use it.

Nunberg concludes that he's going all-in on exclamation points again. It's a good thing, I guess, to get a kind of permission to unleash a little positive emotion in one's writing. But it will take me a long time, I think, before I'll be comfortable with documentation that describes how to use the many! great! features of our products.

[categories]   , ,

|


  02:35 PM

Another quick post about Word, primarily for my own benefit (when I forget this later).

Word has several options for how you can paste text:


They are (in order):
  • Keep Source Formatting. This option keeps the original formatting (both character and paragraph formatting), but converts it to direct formatting.

  • Merge Formatting. This option copies basic character formatting (bold, italics, underline) as direct formatting, but does not copy any paragraph formatting.

  • Use Destination Styles. This option copies the text and applies styles that are in the target document. (This option appears only if there matching styles in the target doc.)

  • Keep Text Only. This option copies the text as plain text, with no formatting.
I need the last one (paste plain text) more often than any of the others, so I want it on a keyboard shortcut. You can do this by recording a macro of yourself using the Keep Text Only option. But I realized there's an even easier way—just assign a keyboard shortcut to the built-in PasteTextOnly command.

I keep forgetting that most anything Word can do has a command. If a gesture requires just one command, you can assign a keyboard shortcut directly to it. Maybe writing this out will help me remember.

Update I added a video!


[categories]   , ,

|


  12:01 AM

This is another in a series of blog posts about how I configure Microsoft Word, which I add here primarily for my own reference.

I often use the Style pane, and within that pane, I often want to change the styles that are displayed. Sometimes I want to see all the styles; sometimes just the styles that are defined in the current document; sometimes just the styles currently in use.

You can change this display by using a dialog box. In the Styles pane, click the Options link, and then use the dropdown lists to select which styles to display and how they're ordered, like this:


But that can get to be an annoying number of clicks if you're switching between these display options frequently. So, macros to the rescue. I recorded myself making one of these changes, then created a couple of variations to give me the different displays I want. Here are the macros I currently use, where the sub name is (I hope) self-explanatory:
Sub SetStylesPaneToAllAlphabetical()
ActiveDocument.FormattingShowFilter = wdShowFilterStylesAll
ActiveDocument.StyleSortMethod = wdStyleSortByName
End Sub

Sub SetStylesPaneToInCurrentDocument()
ActiveDocument.FormattingShowFilter = wdShowFilterStylesAvailable
ActiveDocument.StyleSortMethod = wdStyleSortByName
End Sub

Sub SetStylesPaneToInUse()
ActiveDocument.FormattingShowFilter = wdShowFilterStylesInUse
ActiveDocument.StyleSortMethod = wdStyleSortByName
End Sub
To complete the picture, I map the macros to these keyboard shortcuts:

ctrl+shift+p,aSetStylesPaneToAllAlphabetical
ctrl+shift+p,cSetStylesPaneToInCurrentDocument
ctrl+shift+p,uSetStylesPaneToInUse

[categories]   , ,

|


  12:23 AM

I have used Microsoft Word for years—decades—but hardly a week goes by when I don't learn something new. (Including things that are probably pretty well known to others, oh well.) Anyway, TIL about how to use the batch version of auto-formatting in Word. Since I think a lot of people already know this, I'm adding the information here primarily for later reference for myself.

Word has settings to perform "auto-formatting as you type." These include things like converting quotation marks into so-called smart quotes (i.e., typographical quotation marks), converting double hyphens (--) into em-dashes (—), converting typed fractions (1/2) into typographic fractions (½), etc. You set these options in the AutoCorrect dialog box: File > Options > Proofing, AutoCorrect Options button, AutoFormat As You Type tab.

It turns out that Word can also apply these auto-formatting instructions after the fact. In the same AutoCorrect dialog box, there's a tab named just AutoFormat:


This has most of the same options as with auto-format-as-you-type. Here's the neat part: you can get Word to apply these formatting options by pressing alt+ctrl+k. There's no UI gesture, but you can use the feature for customizing the ribbon to add the relevant command to the ribbon or Quick Access Toolbar.

A use case where I can see this working pretty well is if you paste text in from a text editor. (I do this all the time.)

Credit where it's due: I learned about this from the article How to Automatically Format an Existing Document in Word 2013 by Lori Kaufman on the How-To Geek site. As I say, I'm adding this info here primarily for my own benefit. :-)

[categories]   ,

|


  09:04 AM

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.

SHOULD This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

All of which goes to the original poster's point—the message was ambiguous and should (ha) have been written with must. For those of us who don't keep a mental catalog of RFC recommendations, the more accessible Microsoft style guide says:

Use should only to describe a user action that is recommended, but optional. Use must only to describe a user action that is required.

In documentation, in error messages, in any context where the message needs to be clear and you aren't there to help the reader understand, avoid should when you mean must.

[categories]   , , ,

|


  09:54 PM

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.

[categories]   ,

[4] |


  03:34 PM

Now and again I'll get a request from an engineer that says, essentially, "We need to update the documentation, because there's this additional way to do the task." For example, I got a request not long ago that we were missing documentation for some alternative ways to specify parameters for a command. The command goes like this:

DoSomething.exe --filename <somefilename>

The engineer wanted us to add that you could also do this:

DoSomething.exe -f <somefilename>

In other words, the -f option was a shortcut/alternative for the --filename option.

Similarly, I was recently asked to add a note that told users that under some specific circumstances, they could exclude the filename extension (.pdf or .txt or whatever) from a filename parameter. But leaving off the extension was optional.

When faced with a request like this, the writer might want to take a step back and ask whether the update is really that helpful from the user's perspective: does the reader benefit from this additional information, or does it just add noise? Is this essential information, or is just a nice-to-know?

It's not that these alternative approaches are not useful to users. But does every user have to know every option for every command? Is the benefit worth the extra effort to add them to the docs, and the users' extra effort to sort through the options? What if the alternatives are really just artifacts of the previous version of a command—do we still need to document them?[1]

People who document procedures that involve UI might be familiar with a similar issue. When you're telling the user how to do something, does each step of your procedure describe the menu command, and the right-click context menu, and the keyboard shortcut? This can quickly become cumbersome.

Here's an example of a step from the MadCap Flare documentation that provides an exhaustive inventory of every way to accomplish the step[2]:


Should every procedure step get this treatment? I argue not only that it isn't helpful, but it actually noises up the procedure substantially[3].

The goal of documentation—particularly reference docs and procedures—is to get the user to the solution as efficiently as possible. If you do get requests to include options for commands or gestures, consider pushing back and asking just how necessary these additional options really are.


[1] To alleviate the suspense, I'll note that after consultation with the relevant parties, I said no to the first request and yes to the second.

[2] No keyboard shortcut, because Flare. Grrr.

[3] In my group at Microsoft, we settled on documenting the approach that was the most accessible, in the sense of design for accessibility. That generally meant documenting menus.

[categories]  

[2] |


  10:18 AM

I am all for writing that conveys factual information and that’s written in an informal style. But some rigor is still required, even then, to keep thoughts and facts on track.

Here’s an example, one complete paragraph, from the book Countdown by Alan Weisman, which (as here) sometimes reads like a novel.
It exasperates him to think of agriculture’s driving incentive being not to feed, but to profit. Reynolds rises and stalks to the window. Both these men have made their careers here, working alongside Dr. Borlaug, authoring papers with him. A Nobel Peace laureate, and yet money to continue his work on the veritable staff of life that launched human civilization, and on which it still depends, is so damned scarce.
So, two moments of potential confusion. First, who does “A Nobel Peace laureate” refer to here? Choices seem to include:
  • Reynolds
  • Dr. Borlaug
  • Someone who does not otherwise appear in this paragraph.
Second, what exactly is the relationship between the Nobel Prize and, well, anything in the rest of the sentence that the term appears in?

As I say, informal style is ok with me for a book like this. But if a sentence gets to the point where the reader has to stop and think, even informal writing needs some tightening up.

[categories]   ,

|