Documentation:Keyboard Short Cuts

Documentation > Keyboard Short Cuts

Should keyboard short cuts be required on every step of a process listed in the documentation.

All drafts have been moved to: the main Documentation page, including the most current draft of all provisions, and drafting history.

Feedback/Follow Up from Fact to Face Meeting

From Whitney Quesenbery on February 22, 2007:

The following were comments she received from a documentation/usability list on the question of including keyboard short cuts.

1. Avoid repetition There was general agreement that "four is too many", but many people thought that two primary methods was acceptable.

"A menu sequence, a keyboard shortcut, a right-click popup menu option, and a toolbar icon. Would it be practical for us to include all four options in a procedure every time multiple options exist? No way!"

The advice often boiled down to putting shortcuts and "alternate" (eg. non-mouse) navigation in one place, most commonly "a table" or "an appendix" - it is not always clear if they are talking about online documentation, or how easy it would be to navigate to this information.

"It is always a good idea to have a reference topic for keyboard shortcuts, clearly delineated as such."

Some mentioned introducing all of the control options, to make readers aware of their options, but usually in an introduction and not in all of the procedural topics.

"In the "user orientation" section of the documentation, where the goal is to familiarize users with the system and the various options for navigating and using the system, we actually often DO provide all four means, just so they get the idea that they do in fact have options and can adopt whichever one appeals to them the most. For instance, to open a file, a typical procedure in this orientation material might go something like this:

       1. Perform one of the following actions:
                * From the File menu, select Open.
                * Press CTRL+O.
                * Click the Open File (<sample graphic>) icon.
                * Right-click in the workspace, and from the context menu, select Open."

They often seemed oriented towards printed documents, and to shortcuts as a productivity option.

"Regarding putting a list in the appendix--the user can print the list out and use it as a reference. That's better than nothing--but as a user I would definitely prefer to have the keyboard shortcuts right there in the procedures."

2. Tailor the documentation to the "most common" audience." This could go either way, but the focus was always on use of the application or business audience, not different personas within that audience.

"First, the most common (primary) navigation mode.... The documentation is oriented to this mode. For example, Click Save."

"I write for a business audience--users who were hired to do a job and do it efficiently. So I list the keyboard shortcut first in the documentation, then the slower way (e.g., Press F3 or click Exit [with picture of icon]). Just providing those two options doesn't seem to make it too cluttered."

3. Focus on the "most common" tasks This was a secondary theme, but could lead to the most advanced features, or those not easy to access in the control information architecture being doubly hidden.

"..include the shortcut when you are reasonably certain that the feature will be one that is used often...For very obscure features buried inside a sub-dialog box of a seldom used dialog box (very low frequency of use) then don't include the keyboard shortcut in the doc."

"Anyway, what we do, typically, within a procedure is just to provide whichever option seems to be the most efficient, or the one we *think* our users would be most likely to want to use. I admit freely that this is both tricky and dangerous--as well as subjective--, since we *don't* have any research to back us up."

A few other comments:

"It should be in a table with the left column being the tasks in alphabetical order and the right column being the shortcut. (It should not be in alphabetical order by the shortcut. People do not look up "What does CTRL-A do?" They look up "What's the shortcut for opening a file?""

"Most Microsoft products have a list of their keyboard shortcuts in the Help. PowerPoint lists them by "Tasks" if you search for "Keyboard Shortcuts" and allows you to open them all so they can be printed. The complex Siebel CRM from Oracle actually has a good list of keyboard shortcuts at the top of the generic help which shows common feature and navigation shortcuts."

This all points to the need for better ways of including people with disabilities in general usability programs. Design choices driven by user research can only be as broad as the research that was done. As one person put it:

"What I have tried to do is put myself in the place of my users, as well as I know them."

Initial Email Discussion Of The Topic

These comments are from the initial emails on this topic.

Comment from Jim Tobias on January 4, 2007:

Not if such guidance would be repetitive. For example, every time you want to access the "File" menu in Windows you can press ALT+F. Do I want to see that for every item in the File submenu? No. But all application-specific shortcuts should be available in one place for easy reference, and peppered throughout the documentation as needed.

Comment from Terri Youngblood on January 9, 2007:

The rule of thumb I use when creating documentation is to include keyboard instructions for any actions that do not follow standard industry OS navigation methodologies. For example: If the documentation says, "click on the open icon or select open from the file menu." This is sufficient as long as the file menu keyboard short cut follows the standard shortcut key of "F". If for some reason the shortcut key were, (very problematically - in my view - SMILE), "l" instead of "f" you would need to include this in the documentation. "Click on the open icon or select the file menu (Alt +l) then select "open".

I think it would clutter the documentation to have keyboard short-cuts for EVERY step in the process. There must be at least some basic keyboard navigation knowledge assumed by the author.

Comment from Barbara Lybarger on January 9, 2007:

As an employer who routinely supports three individuals who use vision related AT, and over the years who has supported lots more. I would prefer the documentation include all the keyboard commands required in the technical standards sections. I have three reasons.

First, employees come in at all kinds of skill levels, and having the equivalent keyboard commands right in the documentation puts people with disabilities on the same level with every other new user.

Second, where documentation includes basic level instructions for non-disabled users, one can and should assume the owner of the software thought that level of documentation was necessary and appropriate. If it's necessary and appropriate for non-disabled used, equivalent keyboard commands should also be there for disabled users.

Third, all the commands are needed because employees with disabilities are more often than not part of a team. The technical support folks, co-workers and supervisors of disabled workers need to be able to provide technical support for folks with disabilities that is meaningful for the team to work effectively. That falls apart when one gets stuck on a command that might be basic for an experienced AT user but isn't for the user at hand, and the rest of the support team for that position doesn't use AT and therefore hasn't a clue what the command is and has no readily available place to look it up.

Finally, some might suggest that an appendix with a keyboard command list is a viable alternative to including the commands right in the step-by-step instructions. I've tried to do that and found that it is very cumbersome and confusing because the technical name for commands often has nothing to do with what the command does, and for some reason those who write these appendices often list the information alphabetically by the key strokes used, rather than the function one is attempting to execute.

Comment from Dawn Wilcox on January 10, 2007:

As a visually impaired end user and teacher to others; I agree that the key board commands should be given during the documentation but also have a standard place to be listed in full.

Additional questions:

Comment from Ken Salaets on January 9, 2007:

What have government agencies and federal employees been doing to date to work with products and documentation that do not have or include keyboard short cuts?

Also, should this handed over to the web-software subcommittee for consideration, since it really is a software programming issue?

Response from Debbie Cook on January 9, 2007 on if this should be a web-software issue:

It's a documentation issue because it deals with how they're described, not whether they exist.

Response from Barbara Lybarger on January 10, 2007, on if this should be a web-software issue:

We discussed in an earlier meeting, and this group asked the question of the Web and Software Group after I raised this topic originally. I also had a lengthy discussion about this very question with a member of the Web & Software Group. Their input was that it is not a programming question because it's not about what the program does. Instead, it is about the description in words of what the program does and how to operate it, i.e. the content of the documentation.

Response from Mike Fratkin on January 10, 2007, on what has been done to date:

The more basic issue that we have in the government to date is the fact that most documentation that we receive is not in an accessible format. Once we get past that, it is often difficult to know where to look for keyboard short cuts. Sometimes vendors will say that it is in the standard user guides and sometimes it is in the "accessible" documentation.

It is important to be required on every step but also to provide a list of keyboard short cuts. When I test, I try to use the standard keystrokes to navigate but when I cannot do something, I like to look for the list of keyboard short cuts. The hunt then starts. Is it in the online help, separate documentation, accessible documentation or a call to the vendor?