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

Teacher: a capacity for enthusiasm for the obvious.

Theodore Roethke



Navigation





<May 2016>
SMTWTFS
24252627282930
1234567
891011121314
15161718192021
22232425262728
2930311234

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  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 4/29/2016

Totals
Posts - 2377
Comments - 2531
Hits - 1,840,275

Averages
Entries/day - 0.51
Comments/entry - 1.06
Hits/day - 392

Updated every 30 minutes. Last: 5:36 PM Pacific


  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]   ,

|


  11:50 PM

I’ve had two occasions recently of seeing myself represented in, like, actual books. This is a little startling, in a pleasing kind of way.

The first reference is explicit. In his book Engineering Security (or at least in the April 2013 draft of it—download it here), Peter Gutmann is discussing the problem of putting security decisions in front of users. Here’s a paragraph out of that chapter:
The abstract problem that the no-useless-buttons policy addresses has been termed “feature-centric development”. This overloads the user with decisions to a point where they adopt the defensive posture of forgoing making them. As Microsoft technical editor Mike Pope points out, “security questions cannot be asked on a ‘retail’ basis. The way users make security decisions is to set their policies appropriately and then let the security system enforce their wishes ‘wholesale’”
Boy, was I tickled when I ran across that. But I didn’t remember being that smart, so I went to the blog to figure out where I had said such an interesting thing. Alas, although it is true that this information appears on my blog, it’s actually a citation from the eminently quotable Eric Lippert, who knows a great deal more about security than I ever will.

And then today I was reading Steven Pinker’s new book A Sense of Style. This is Pinker’s shot at a guide to writing (i.e., a usage guide), with the twist that Pinker is a cognitive psychologist, so he proposes guidance for clarity and comprehensibility in terms of how the brain processes the written word. (It’s more interesting than I’ve just made it sound.)

At one point, Pinker is talking about how the “geometry” of sentences determines how well readers can comprehend them. For example, it can be problematic for readers to parse long “left-branching” constructions, where qualifiers come at the beginning of the sentence: “if [the modifier] starts to get longer it can force the reader to entertain a complicated qualification before she has any idea what it is qualifying.”

He has a number of examples, including the following:
  • The US Department of the Treasury Office of Foreign Assets Control

  • T-fal Ultimate Hard Anodized Nonstick Expert Interior Thermo-Spot Heat Indicator Anti-Warp Base Dishwasher Safe 12-Piece Cookware Set.
And here’s another of this examples:
  • Failed password security question answer attempts limit
Ha! I thought. I know exactly where he got that last example: from me. Well, sort of. Once upon a time I wrote a blog entry about “noun stacks”—big ol’ piles of words like these examples. In the entry I included a number of examples that I had run across at Microsoft. The blog entry was picked up by the Language Log, which is undoubtedly where Pinker actually found the example. But I know where that example really came from.

Naturally, many people find themselves cited constantly, both formally (like, academics) and in popular writing. I suppose a person can get used to reading along and seeing something they’ve written cited in an article or book or whatever. For me, though, even just these tenuous associations with real books is quite exciting. :-)

[categories]   ,

[1] |


  09:58 AM

Andrey Karpov, who analyzes software for defects, has identified what he calls the "last line effect." This happens when people use copy and paste to quickly create a bunch of similar lines of code. He's figured out that mistakes are most often made in the last pasted block of code. He backs up his thesis with hard numbers and with examples taken from real code. He muses:
I heard somewhere that mountain-climbers often fall off at the last few dozens of meters of ascent. Not because they are tired; they are simply too joyful about almost reaching the top—they anticipate the sweet taste of victory, get less attentive, and make some fatal mistake. I guess something similar happens to programmers.
I've certainly made this mistake while writing code. This also made me wonder how often this syndrome is evident in writing or editing. What would this look like? Obviously, there are many pitfalls associated with copying and pasting, but is there an analogue in writing and editing to the last line effect?

[categories]   ,

[1] |


  06:41 PM

As a technical writer, you will frequently find it useful to be on the consuming end of information and to take some lessons away from that experience. I had such an experience today.

I was working with some internal tools and couldn't get things working. I pinged the experts, and one of them sent me back instructions that ran something like this (altered to be suitable for public consumption):

1. Save the attached configuration file.
2. Overwrite the current config file in the X folder.
3. Try the process again.

I saved the file and overwrote the config file. No luck, so I contacted the expert again. I got this response:

Please follow the instructions exactly.

So, I tried again. Still no luck, so I sent a dense response detailing what I'd tried and where it had failed. The expert, I must say, became a little impatient.

Long story short, the process I was trying has two configuration files in two places. I had overwritten the wrong one. The part of step 2 that said "in the X folder" had somehow not penetrated to me, probably because I was looking right at an actual configuration file and I had no reason to imagine that there were two of them. So the "in this folder" qualification hadn't really registered.

It's arguable of course that it's my own damned fault for not reading the instructions carefully enough. But I've done (and indeed, still do) technical support, and I generally don't blame customers for not being careful enough in reading the docs. If instructions aren't working for people, I try to take away a message that the instructions aren't clear enough. I certainly don't respond to confused customers with the message that they're just not reading instructions carefully enough—especially the instructions that obviously don't seem to be working.

But those are after-the-fact issues. What would have prevented the confusion in the first place is for the expert/writer to have anticipated a possible problem, along these lines:

2. Overwrite the current config file in the X folder. (Note that there are two config files—make sure you overwrite the one in folder X.)

That is, it helps tremendously if the writer can anticipate trouble spots and steer the reader around them. Of course, it would be best if processes didn't have such trouble spots—why are there two files with the same name in different folders?—but there are many cases where things are just going to be a bit confusing, oh well.

It would have saved an hour or more of time, not to mention aggravation on both sides, if this small issue would have been anticipated.

So look out for where users might be confused when reading docs. And if readers tell you that they're confused with your existing docs, take that as your problem, not theirs.

[categories]  

[1] |


  11:13 PM

I just installed Word 2013 and was disappointed to note that some of the long-standing keyboard shortcuts no longer work. For example, I've been using Alt+V,A for years (decades?) to invoke an ancient menu command to toggle between hiding and showing revision marks. Even when they introduced the ribbon and the menus went away, a lot of those old menu-command shortcuts still worked. And some still do; but this particular one no longer does, darn it.

I spent a little while trying to map keystrokes to the show-revision and hide-revision commands in the Review tab. Either I'm not finding them or (as I believe) there's no longer a single command to toggle show/hide of rev marks in the way I've come to rely on.

So, macro time. Using the macro recorder and some editing, I created the following macro and then mapped Alt+V,A to it. Macros are stored in Normal.dotm, so as long as that remains available I should be good. (Right?) However, I'll have to update Normal.dotm on each machine on which I install Word 2013.

Update 2016-03-06: For the "hide revisions" section, I changed wdRevisionsViewOriginal to wdRevisionsViewFinal. This macro always shows the "final" version, but toggles whether rev marks are displayed.

Perhaps there's an easier mapping for this functionality. If this macro thing doesn't work out, I'll investigate further.
Sub ShowOrHideShowRevisions()
If ActiveWindow.View.RevisionsFilter.Markup = wdRevisionsMarkupNone Then
' Hide revisions
With ActiveWindow.View.RevisionsFilter
.Markup = wdRevisionsMarkupAll
.View = wdRevisionsViewFinal
End With
Else
' Show revisions
With ActiveWindow.View.RevisionsFilter
.Markup = wdRevisionsMarkupNone
.View = wdRevisionsViewFinal
.View = wdRevisionsViewOriginal
End With
End If
End Sub

[categories]   ,

|