Copyright TASullivan

py g

1
Personas help us identify the true users of the application and the 
p y pp
documentation. They help us understand who really uses the application 
to perform the tasks. It’s too easy to think of ourselves as the users – to 
identify with our own ideas of how the application should be or could be 
used.

Instead, we must identify with the true users and their tasks so we can 
know the parts of the application they will find intuitive and the parts 
they will need help understanding.

Develop personas of your true users—the actual client who will be using 
the software and (therefore) the user documentation. Personas help you 
to understand user motivations, expectations, and goals. Post personas 
for your projects next to your PC, and then use the persona as your focus 
to help you develop the “voice” (tone) of your documents. Knowing your 
tr e ser also helps o to kno ho j st ho detailed to make o r
true user also helps you to know how just how detailed to make your 
document.

2
No matter what comfort level users have, they want immediate answers 
, y
to any problems they encounter. They want to find and understand 
solutions in the least possible time so that they can continue with their 
tasks.

Understanding their expectations is critical to creating successful user 
Understanding their expectations is critical to creating successful user
documentation. All three groups expect to find and understand the 
answers to their technical problems immediately – preferably on the 
screen. If they don’t, they will call for support.

Remember that technology “resisters” are declining as “innovators” are 
increasing. Just as software engineers are building applications to meet 
user needs (not merely functional needs), we must create deliverables 
that are truly usable for the right group of clients.

3
Taking time to identify the personas involved in your project enables you 
g y p y p j y
to more easily understand and gather information from project sources, 
such as requirements, use cases, and wireframes. 

Requirements, use cases, and wireframes all relate to the users’ tasks 
and workflows using the information garnered by BAs and UX associates’ 
research and interviews. As writers, we need to be able to analyze, 
understand, and use these requirements, use cases, and wireframes to 
identify the tasks and workflow Knowing this helps us to write our 
content in a more user‐focused way. It also helps us clarify our writing 
style by helping us identify the terms we should use when referring to 
diff
different features or aspects of the tasks and the application. Clients 
tf t t f th t k d th li ti Cli t
generally prefer simple, non‐technical language. If we must use a 
technical term, we better be able to explain it simply and clearly the first 
time it appears. 

4
Once you know who the true user is, you need to apply the concepts of 
y ,y pp y p
heuristics, usability, and PET to your documentation. 

Applying heuristic principles to user documentation means more than 
adopting a different writing style. It also means thinking and working 
differently too That means looking at your clients from their
differently, too.  That means looking at your clients from their 
perspective, not yours. 

5
To see your client from your client’s perspective, you have to first 
y y p p ,y
understand what their perspective is. You have to understand that your 
clients are trying to complete a task that helps them complete their 
workflow, and that is why they are using the application. If you can grasp 
that, then you can actually help your clients achieve their goal: 
completing their work in a quick and efficient way.

Let’s start by spending a few minutes examining the differences between 
user workflows, user tasks, and software functions.

6
In the past, a client’s workflows were not always on the mind of either IT 
p , y
or the business. Consequently, user documentation often included 
involved steps to explain gaps between the user’s tasks and the 
application’s functions. However, with usability as part of the design 
team, along with BAs and product managers, there is more interaction 
with the users to determine the users’ tasks and workflows. The UX team 
and the BAs then develop design documents that help the software 
engineers create applications that more closely mimic the users’ actual 
workflows.  

Those same documents can help us create user documentation that is 
more user‐focused and task oriented. While this may seem like a simple 
f d d t k i t d Whil thi lik i l
concept, we often get lured into describing how the application works 
rather than how the user works. This graphic clearly separates the 
application functions from the workflow and tasks; we need to be sure 
we don’t move away from documenting the user’s workflows and end up 
documenting the application instead
documenting the application instead. 

7
Most users perform more than one workflow in order to complete their jobs, and 
sometimes the same task can appear in multiple workflows. For instance, the task of 
making and logging phone calls in Microsoft’s CRM product occurs in the workflow of 
managing clients, as well as in the workflow of creating campaigns.  

User’s workflows are important because: 
• They define the number and type of audiences.
They define the number and type of audiences.
• They are a roadmap to the tasks.
• They help define possible deliverables.
• They provide the organization for documentation.

8
Heuristically, we want to document user workflows and tasks, not software functions. 
Users only care about software functions in the context of completing their tasks.

Driving to Work is a workflow that contains multiple tasks. These tasks also require the user 
to learn and use several functions of the car.

9
In our example, the workflow (Driving to Work) contains 3 user tasks. However, it’s easy to 
slip into the simpler mode of documenting the functions, such as:

•Understanding the Shift Lever
•Manipulating the Steering Wheel
•Using the weather controls in the car

While it may seem helpful to include information regarding the application users really just
While it may seem helpful to include information regarding the application, users really just 
want to know how to use the tool so they can complete their work. Therefore, if it isn’t 
part of one of their workflows, think twice about including it.

10
User’s jobs usually entail more than one workflow. Workflows are usually comprised of 
more than one task—not always, but most of the time. Tasks can be done independently of 
the workflow and of other tasks—again, not always, but sometimes. Tasks can sometimes 
entail several screens or menu options of an application to complete.

What does this mean when you are writing documentation?
• You need to find out which of the user
You need to find out which of the user’ss workflows are included or impacted by the 
workflows are included or impacted by the
project. 
• You will probably have to group several user tasks together to complete a single user 
workflow (Driving to work—the user workflow—requires the tasks of starting the car, 
steering the car, and finding their way).
• You may have to analyze several application functions to understand and document one 
user task.
user task
• You shouldn’t mistake application functions for user tasks – be sure the topic headings 
still describe user tasks, not application features.

Remember that your focus when writing is the user and his or her workflow, not the 

application and what it can do. 

11
Whenever possible, talk or listen to the users as they describe their workflow. Keep in mind 
that users may underplay or omit sections in their workflow –
h d l i i i h i kfl they know it so well that 
h k i ll h
they sometimes forget to mention everything.

User representatives, such as product managers, can also be helpful in confirming the 
workflow.

12
13