Text, annotated screen captures and screen movies are all useful when discussing or explaining the use of a computer program.
Establish a set of conventions for describing keys, menus, buttons and interactions. The following section provides a recommended style. As always, the main rule is to be consistent. This means not using PrtScn in one place and Print Screen in another; if using PrtScn, use PgDn and other shortened versions.
For any instructions, accessibility can be improved by mentioning more than 1 path to the same result:
Keyboard and mouse
When referring to the keyboard, use maximal capitalisation for the key names:
Ctrl Alt Shift Home Print Screen F5 Space Backspace Page Down M
Do not write the key names in quotation marks or enclose them in angle brackets.
Caution. Not all keyboards have the same keys, and new keys are added from time to time. Avoid referring to media keys (e.g. volume up and down), computer control keys (e.g. screen brightness) and specialised keys (e.g. to launch search or a mail program) unless sure that readers have the same keys.
Also take care when writing for international audiences, because keyboards for different countries are not the same. For example, the United Kingdom keyboard includes a pound sterling sign (£) and has some other symbols in different positions, compared with the United States keyboard, which is used in Australia.
Some keys are labelled differently from keyboard to keyboard:
PgDn or Page Down PrtScn or PrtSc or Print Screen Ins or Insert Del or Delete
If necessary, define the key name the first time it is used:
Press the Menu key; it is usually found immediately left of the right Control key and may look something like this: ▤.
Use the names even when keys are also known by a symbol, because symbols can change from keyboard to keyboard and version to version:
Windows Key rather than
Command rather than
The Space key usually does not have a label, but because Backspace uses a capital, it is consistent for Space to use a capital. Capitalisation is also useful because space is a relatively common word.
Insert a space by pressing Space.
Key combinations
When giving combinations of key presses, join the letters with an unspaced plus (+):
Shift+F3 Ctrl+A Ctrl+Shift+A Ctrl+Alt+Del Command+N
Specify all key presses – do not leave Shift implicit:
Use Ctrl+Shift+8 to toggle invisible characters on and off.
not
Use Ctrl+* to toggle invisible characters on and off.
For taps and mouse clicks, use hyphens:
Right-click for the context menu.
Double-tap the OK button.
Key combinations may differ between operating systems. Mac users may need different instructions from Windows users, or the system to which the instructions apply may have to be specified. For example, the Delete key on a Mac keyboard works like the Backspace key on most other keyboards. You will need to know which system your users have, or provide instructions for both.
Menus
For menu entries, use maximal capitalisation:
This helps the reader see where the name of the item ends and the text resumes, and so reduces ambiguity:
Choose the Inspect Document option.
not
Choose the Inspect document option.
[The latter could mean that Inspect is one of a series of document options.]
If the application you are describing does not use maximal capitalisation, your instructions will not accord exactly with what the user sees on their screen. This is acceptable.
Capitalise icon and button names:
If the icon does not include text, will readers know which icon to click? Make sure the description is clear. Users may see something different from you. For example, some applications allow a menu to be displayed as icons, icons plus text, or text. Be as precise as necessary, and avoid invalidly assuming everybody has the same setup as you.
Indicate items to be chosen from nested menus using a greater than sign (>):
Typing commands
Do not use quotation marks in instructions unless the reader is required to type them:
Microsoft Word can be launched from the command line by typing:
C:\> "c:\program files\microsoft office\root\office16\winword.exe"
When indicating user input on a command line (e.g. at an onscreen prompt), use a monospaced font (because the command line will use such a font) and write the program name as a user would write it. Try to make the instructions agree with what the reader is likely to encounter:
$ pdflatex myfile.tex
Here, $ is the onscreen prompt, pdflatex is the program and myfile.tex is the file the program is to process.
This use of monospaced font differentiates between the application name and the name of the underlying executable file that starts it running:
When you click the menu entry for Microsoft Word, the program winword.exe is launched.
Word-processing styles
Entities such as custom styles defined in a word processor or design program can have names that contain almost any combination of letters, numbers and spaces. The names may be long and cannot be maximally capitalised because the definitions are case-sensitive. To clearly separate them from the surrounding discussion, use single quotation marks or italic (but not both):
Select the ‘Table notes’ style.
or
Select the Table notes style.
If your document refers only to 1-word styles, it is probably unnecessary to use any styling:
Normal Heading 2