133LANG4030 Communication in Professional Contexts
WRITING USER GUIDES
Pre-task activity: Adding explanations to instructions
The following instructions about computer usage might be given to staff in a company:
 Select a network password of no more than 8 characters which includes letters,
numbers and symbols.
 Back up all your important documents onto an external hard drive.
 Enable automatic updates for your anti-virus software.
People usually like to know why they are being asked to follow an instruction, and to know
what the consequences will be if they do or do not take action. What could you say to:
 Provide more explanation of what the instruction means?
 Illustrate the consequences of not following the instruction?
Task 7: Going beyond instructions
Instructions play an important role in helping users to handle tasks but the technical writer has
to go beyond giving instructions to give a comprehensive introduction to and explanation of a
computer product or system.
1. You will watch part of an instructional video which tells OpenCart users how they can
create listings on eBay for their OpenCart products. You will use the information in the
video to supplement the very brief instructions below to create a more informative and
user-friendly section of the user guide.
 Before you watch the video, read the instructions. What extra information and
images might be needed?
 Watch the video and make notes. Then supplement the instructions with more
information, to enable the users to perform the task.
You will:
 Add supplementary information
to instructions in a user guide
 Analyze language and style in
user guides
2.3
134 LANG4030 Communication in Professional Contexts
Creating listings on eBay using your OpenCart Products
You can create listings on eBay, using products which you already have in your OpenCart
store.
To create a new listing, login to your admin dashboard
Click on Extensions, choose OpenBayPro, and then select Manage items
To choose a product, click on the eBay icon, below Markets
Select the eBay category that your product matches
If none of the suggested or popular categories match, select the category manually
Select from the categories in Item Condition and Listing Duration
Available at: https://www.youtube.com/watch?v=jCFUR_yigZg
2. The two texts overleaf are taken from guides targeted at different types of user. Read the
extracts and note down what additional information is given to users to supplement the
instructions.
Supplementary information Text 1 Text 2
1. Giving a task overview
2. Listing pre-requisites for performing the task
3. Giving examples of usage
4. Stating what will be achieved by following
the
instructions
5. Giving a warning
135LANG4030 Communication in Professional Contexts
Text 1: Extract from the edX User Guide
2.1. Getting Started with edX
The following topics provide an introduction to edX and instructions for getting started on
edX websites.
 edx.org and edX Edge
 Create an Account
This information is intended for course teams. You might want to share course- or
institution-specific details about the registration process, such as password policies or the
use of campus credentials, in your communications with prospective students.
2.1.1. edx.org and edX Edge
To explore edX courses, you can register an account on the edx.org website, the edX Edge
website, or both. These sites are visually and functionally similar, but their content and
purposes are different.
 edx.org hosts massive open online courses (MOOCs) from edX institutional partners.
To publish a course on edx.org, you must have an agreement with edX and specific
approval from your organization. Courses on edx.org are publicly listed in the edX
course catalog and are open to learners from around the world.
 Edge, at edge.edx.org, is a more private site. Courses on Edge are not published on
edx.org. Any member of a partner course team can create and publish courses,
including test courses, on Edge without receiving approval from edX or a partner
institution.
Note: All course data and user accounts on Edge and edx.org are separate. If you want to use
both edx.org and Edge, you must complete the account registration process on both sites.
2.1.2. Create an Account
Before you create, or register, your account, note the following.
 If you are at an edX partner institution, be sure to supply your institutional email
address or select an existing account (such as a campus account) that is set up to use
your institutional email address.
 Learners and other course team members will see the name that you enter as your
public username, not your full name. You cannot change your public username after
you register.
To register an account on the edx.org or edX Edge website, go to the edx.org registration or
Edge registration page.
136 LANG4030 Communication in Professional Contexts
Source: https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/getting_started/CA_accounts.html
137LANG4030 Communication in Professional Contexts
Text 2: Extract from Matomo (Piwik) user guide
Manage Users
The best way of giving people access to your Matomo (Piwik) data is to let them use
Matomo. Each user will be able to set up a dashboard that suits their priorities and needs.
For example, your marketing department may concentrate on how people are getting to the
site, whereas the website manager may need information on the website’s goals and
conversion rates. When they need more information, it will only be a few clicks away.
Create Users
To add users, you need to be signed in as the super user. When you are, click on
Administration to access the administration area.
Then click on the Users tab, and you will see this screen:
Click Add a new user to turn the table into a form. Fill in the details and click save. The
message ‘your changes have been saved’ will appear to confirm that you have created the
new user.
Source: http://piwik.org/docs/manage-users/
138 LANG4030 Communication in Professional Contexts
Language focus 1: Using verbs in passive voice
Passive voice is often used in user guides when giving further information or describing the
results of taking a step. However, some verbs cannot be used in the passive voice.
Which of the underlined verbs in the four sentences below cannot be used in the passive
voice?
Example sentences: Correct?
1. Visitor Profile dashboard widget: The visitor profile can be embedded
as a dashboard widget.
2. This will open a new window/tab with the visitor profile alone. The URL
for this new page can be used to embed the Visitor Profile for that
specific visitor.
3. You can add more language choices by selecting from the options under
Language. The new language option will be appeared in the language
list.
4. Open your web browser and navigate to the URL to which you uploaded
Piwik. If everything is uploaded correctly, you should see the Piwik
Installation Welcome Screen.
These are some other commonly used verbs in user guides. Which of them cannot be used in
the passive voice?
select show occur display enter disappear scroll
update save retrieve respond swipe
Language focus 2: Old to new information flow in User Guides
User guides need to be coherent and easy to follow. In the previous section of the course, you
learned about a useful way of making information flow smoothly from one sentence to the
next:
“Old” (or known) information is commonly placed at the beginning of the sentence. Old
information tells the reader the topic of the sentence.
“New” (or unknown) information is commonly put at the end of the sentence.
139LANG4030 Communication in Professional Contexts
You can make your user guides more coherent by keeping old to new information flow in mind
when you write. Read the following two extracts from the Matomo User Guide and select the
sentence that you think makes the writing easier to follow.
The Visitor Profile
The Visitor Profile, introduced in Matomo, helps you to understand your visitors’ individual
behavior by summarizing and listing your visitors’ visits. Using the information displayed on
the Visitor Profile, you’ll be able to better understand:
 why your visitors viewed your website.
 why your returning visitors continue to view your website.
 what specific visitors are looking for and whether they found it on your website.
Launching the Visitor Profile
The Visitor Profile can be accessed through the Visitor Log (the Visitor Log can be accessed
by navigating to Visitors > Visitor Log). 1. _________________:
2._________________________________________________.
1A. When you hover over a visit, a link will be displayed:
1B. A link will be displayed when you hover over a visit:
2A. The visitor profile for the site visitor will be launched when you click on this link.
2B. Clicking this link will launch the visitor profile for the site visitor.
Advanced Uses
Exporting visitor profile data
The data displayed on the visitor profile can be exported to other formats, such as XML,
JSON, CSV, etc. 3. __________________________________. Then hover over the visitor ID
and click the export link that appears:
This will show you the data in XML format. 4. ________________________.
Visitor navigation
140 LANG4030 Communication in Professional Contexts
You can also navigate within the visitor profile popup to older or more recent visitors.
5.____________________________________________________:
Clicking on the left and right arrows will change the visitor to the next more recent/less
recent visitor, respectively.
You can also press the ‘left’ and ‘right’ arrow keys to change the visitor.
Source: https://matomo.org/docs/user-profile/
3A. First open the visitor profile for a visitor to export this data
3B. To export this data, first open the visitor profile for a visitor
4A. If you’d like to change the format, locate the format=xml part of the URL and change
it to the format you’re looking for (for example, format=csv)
4B. Locate the format=xml part of the URL and change it to the format you’re looking for
(for example, format=csv) if you’d like to change the format
5A. When you hover over the top left section of the popup, two arrows will appear
5B. Two arrows will appear when you hover over the top left section of the popup
Out-of-class activity: Assignment Checkpoint 3
We have talked about the first section of the user guide, that is, the overview to tell the user
what the app is, why it is needed and what major features it has got. The next thing to do is to
think of other suitable sections with appropriate headings.
After deciding the sections you have, you may try writing a section to get some feedback. You
can find two samples on pp. 136-137 but they are NOT perfect.
Please upload a section of a user guide to Canvas>Assignments>Assignment Checkpoints>Unit
2.3 Writing a section in a user guide (Checkpoint 3). After getting the suggestions, you can
finish the user guide and upload your assignment to Canvas.
Tips
 refer to samples, think about the format and layout,
and make it look more professional like a user guide
(add page numbers)
 think about whether the text or the image should
appear first, and the text and the corresponding
image should be on the same page
 separate long paragraphs / present instructions step
by step but not in a para
 start a section with a mini-overview instead of a
sub-heading
 add screenshots (clear, big enough and full without
cropping) and highlight/label the part to show what
you refer to
 you may need to use an example to make the
instructions easier to follow
 think about the organization/layout/format of the
contents (put them in a sensible order/place)
 there is no need to be detailed about everything
(e.g. how to open a file), but instead you can