Font Styles
When documenting software applications, it is important to provide the reader with visual cues to help bring clarity to your instructions.
As far as possible colour should be avoided as it can cause problems for some readers such as those with a visual impairment.
To overcome this, we use different font styles to make key points stand out from regular text.
To ensure that we can apply these styles in a uniform manner and change them globally should we need to, we use the HTML class attribute.
The different class attributes currently available are listed in this section together with an example of when to use them.
Component Titles
Software applications frequently have a variety of windows, forms, wizards, and pages. These are identified with the "wintitle" class.
In the following example the "wintitle" class has been applied to the words 'File Explorer'.
-
To find a file on your laptop:
-
Click
.The File Explorer window appears.
You can now search for the file you are looking for.
-
User Interface Control
User interface controls are elements in the software application that a user can interact with such as tabs, icons, menu items, and fields. These are identified with the "uicontrol" class.
In the following example the "uicontrol" class has been applied to the words 'Password' and 'OK'.
To change your password:
-
Click the Password tab.
A pop-up box appears.
-
Enter your new password in the Password field.
-
Click OK.
Your password has been changed.
Links
Some user interface controls are hyperlinks which, when clicked take the user directly to a specific location such as a web page. These are identified with the "uilink" class.
In the following example the "uilink" class has been applied to 'NEC'.
-
Click the NEC link to visit our website.
Buttons
Often users are required to click a button to continue the processes that they are following. While it is not necessary it can bring clarity if the button text is rendered to look like the button they need to click. Buttons are identified using the "uibutton" class.
This span can be used instead of the "uicontrol" class provided it is used consistently throughout the online help or document.
-
uiCharacterButton
In the following example the "uiCharacterButton" class has been applied to the word 'OK'.
Click the OK button.
-
uiWinButton
In the following example the "uiwinbutton" class has been applied to the word 'OK'.
Click the button.
Note
This is displayed as a button in the online help.
-
uibutton
In the following example the "uibutton" class has been applied to the word 'OK'.
Click the button.
Note
This mimics a button in online help but renders as bold text in MS Word documents.
File Paths
A file path is the route the user needs to take to access a specific location within the software, on a server, or to a website. File paths are identified using the "filepath" class.
In the following example the "filepath" class has been applied to navigation path that the user needs to follow to locate the folder that documents are downloaded to on their laptop.
-
To find a recently downloaded file navigate to your downloads folder:
'C:\Users\my-name\Downloads'
System Output
Software applications sometimes respond to actions a user takes by displaying a message or key information on the screen. The user's attention is drawn to these responses using the "systemoutput" class.
In the following example the "systemoutput" class has been applied to the error message that the user will see.
-
Enter your username and password.
If either of these are incorrect the following message will be displayed:
'Error 101: Incorrect username or password, please try again.'
-
Click OK to authorise the transaction.
The transaction has been approved and the status changed to 'A'.
User Specific Data Entry
Software applications sometimes require users to enter specific information, such as a licence key. Under these circumstances it is important that the user can identify the text that they are expected to enter. This is done using the "userinput" class.
In the following example the "userinput" class has been applied to the licence key text.
- Enter the licence key: 'ABCDEFG-123-X'
Options
Software applications often present the user with a choice of options to select from. These are identified using the "option" class.
In the following example the "option" class has been applied to the words, 'Coffee', 'Coffee-M', and 'Coffee-MS'.
-
Select one of the following:
-
Coffee - to dispense coffee without milk or sugar.
-
Coffee-M - to dispense coffee with milk.
-
Coffee-MS - to dispense coffee with milk and sugar.
-
Parameter Names
System parameters are often used in software applications to switch on or off particular features. To ensure that users know which one they need to use, parameters are given a unique name. When documenting parameters their names are highlighted using the "paramname" class.
In the following example the "paramname" class has been applied to the name of the parameter.
-
Use the MY_FAV_ITM parameter to display or hide your favourite items.