Professional Documents
Culture Documents
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.
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