About

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

Read more ...

Blog Search


(Supports AND)

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

A writer who fixes too much attention on the correctness of his punctuation, or a reader who does the same, is missing the point: the job of text is to communicate, not satisfy pedantic rule makers.

Michael Quinion



Navigation





<February 2025>
SMTWTFS
2627282930311
2345678
9101112131415
16171819202122
2324252627281
2345678

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

Contact Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 9/4/2024

Totals
Posts - 2655
Comments - 2677
Hits - 2,726,430

Averages
Entries/day - 0.34
Comments/entry - 1.01
Hits/day - 345

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


  11:51 PM

I recently ran across the following set of instructions (the name of the app — MyApp — is changed, but they're otherwise verbatim):

Setup Instructions
1. From the Setup Location, run MyApp.msi.
2. Click Next.
3. Click Next for the default install location, or set the install location.
4. Click Next.
5. After installation is complete, click Close.

This a terrible set of instructions. For starters, an .msi file is an installation program (Microsoft Installer). When you launch an .msi, it starts an installation wizard. A wizard (a.k.a. assistant), which is to say, a process that walks you through each step of the process. Wizards were created precisely for multi-step processes so that users didn't need step-by-step instructions. And it doesn't matter whether you know that an .msi file will launch the wizard — all you need to tell people is to launch the .msi, presto, done. If this just seems too bald for you, well, fine, add "... and follow the on-screen instructions" or some other yeah-yeah-whatever text.

Second, these instructions are not telling you what to do in context. "Click Next." Click Next." These instructions are like telling someone how to do something blindfolded.

Third, when they do provide a pretense of information ("Click Next for the default ..."), they're a) repeating what the wizard is already telling you and b) telling you, essentially, "make a change, or don't." The instruction doesn't provide any useful information about how or why to make a choice, just that you might want to (or not). Which will already be evident from the wizard, see point 1.

Fourth, for god's sake, even my grandmother would know enough to close an app when she's done with it.

Finally, all of this is in the context of a tool that we use at work. Surely if anyone knows how to navigate an .msi installation wizard, it's people who work at Microsoft. So even if there were useful information in these instructions, they don't take into account the audience, which basically consists of people who've probably run hundreds of .msi installers before.

Really the takeaway here is that sometimes you just don't need to write any instructions at all, because users don't need them. In those cases, well ... don't.

[categories]   ,

[2] |