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

The cure for a fallacious argument is a better argument, not the suppression of ideas.

Carl Sagan



Navigation





<November 2019>
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 Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 11/8/2019

Totals
Posts - 2584
Comments - 2621
Hits - 2,184,218

Averages
Entries/day - 0.43
Comments/entry - 1.01
Hits/day - 365

Updated every 30 minutes. Last: 11:22 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] |