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

In object oriented systems, there is a bit of mental judo going on whereby you convert a system from imperative statements like "print x" to a more message oriented "to: x; message: go print yourself".

Sam Ruby



Navigation





<December 2017>
SMTWTFS
262728293012
3456789
10111213141516
17181920212223
24252627282930
31123456

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  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 12/8/2017

Totals
Posts - 2465
Comments - 2567
Hits - 2,005,851

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

Updated every 30 minutes. Last: 1:52 AM Pacific


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