Instructions for programs, websites and applications

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:

Right-click anywhere on the screen or press the Menu key.

This sections covers:

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 (eg volume up and down), computer control keys (eg screen brightness) and specialised keys (eg 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.

Return to top

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.

Return to top

Menus

For menu entries, use maximal capitalisation:

Save     Save As     Create a New Profile     New Tab

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:

Press the Cut icon.

If the icon does not include text, will readers know which icon to click? Make sure the discussion 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 (>):

Select: Window > Move To > Left Side, and click OK.
Return to top

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 (eg 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:

Run PDFLaTeX by typing pdflatex at the prompt.
When you click the menu entry for Microsoft Word, the program winword.exe is launched.
Return to top

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

Return to top

User login

... or purchase now

An individual subscription is only A$60 per year

Group and student discounts may apply

Australian manual of scientific style Start communicating effectively

Purchase