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

Whenever someone asks me to define love, I usually think for a minute, then I spin around and pin the guy's arm behind his back. Now who's asking the questions?

— Jack Handy



Navigation





<August 2020>
SMTWTFS
2627282930311
2345678
9101112131415
16171819202122
23242526272829
303112345

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 Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 7/27/2020

Totals
Posts - 2626
Comments - 2635
Hits - 2,286,815

Averages
Entries/day - 0.42
Comments/entry - 1.00
Hits/day - 366

Updated every 30 minutes. Last: 6:40 PM 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] |