May 07, 2015
Not every option has to be documented
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
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?
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:
Should every procedure step get this treatment? I argue not only that it isn't helpful, but it actually noises up the procedure substantially.
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.