Transcript Real task - Learning DITA

Writing Task-Oriented
Documentation
The core of quality end-user documentation
Overview
•
•
•
•
•
Review the three topic types
What is “task-oriented” writing and why do we need
this session?
The challenging of the task
Tips for writing task-oriented doc
Summary and Q&A
Content derived primarily from Developing Quality Technical Information: A Handbook for
Writers and Editors, by Gretchen Hargis (Editor), Ann Hernandez, Polly Hughes and Jim Ramaker,
Prentice Hall, 1997, ISBN 0137903200.]
A review: the three topic types
Concept
•
•
•
•
describes why and what
Justification  Why do I need this info?
Navigation  Am I on the right page?
Features & Limitations  Can I save this information?
Goals  What can I do with this application?
Task
describes how to perform a task
• Procedural Typically involves numbered steps
• Task steps  How do I complete my task?
• High-level process  What do I do next?
Reference
•
•
•
•
•
provides details necessary to make decisions
Descriptions  What does this button do? What does this acronym mean?
Examples  What's a good password?
Exceptions  What if I have two middle names?
Relationships and dependencies  How do these settings relate to each other?
Expectations  How long will this take?
What is task-oriented writing?
• It is writing centered about a user goals of completing
certain tasks
• The focus is NOT…
• How the product works
• How the product is structured
• Why is this approach desirable for end-user documentation?
• Most users go turn to documentation when they need to know how to
do something, not to gain general knowledge. This type of content is
known as ”read-to-do” content.
• Contrast with “read-to-learn” content, which is what we are likely
exposed to within the education process, e.g. text books. It is typically
designed to help students learn about something (i.e. conceptual)
rather than how to do something.
Why do we need this discussion?
•
It’s not simply
• Task = good
• Reference/concept = bad
• Obviously, all three are important and there is a time and place
for each.
• Objective is to shift overall focus/orientation towards the task
• Why now?
• Many of us are working with documentation that has deep
roots in the past…many of US have deep roots in the past! ;)
• Times have changed, UIs have changed…users have changed!
• Now is prime time to reassess what you do.
What has changed?
Design and user comfort:
• Increased UI usability and more intuitive
designs
• More knowledgeable, savvy users
• Embedded user assistance more and more
common
Demands on time:
• Less time for learning
• Shorter attention spans
• Fewer UX resources…need to
concentrate efforts where they
matter most!
What now? Tips for approaching the task…
Focus on real
user tasks,
not features
and functions
Beware the artificial task!
Know the difference between real and artificial tasks.
• Real task:
A task that users want to perform, regardless of
whether they are using your product to do it.
•
Artificial task:
A task imposed by the product; don’t assume users
understand the task in terms of the tool.
The challenge of determining the “real” task
•
Describing a system’s user interface and creating
procedures that follow UI navigation is easy, so easy a
robot can do it!
•
•
It is also deceptive. Real tasks are often more complex.
•
To write truly helpful, task-oriented doc, we need to
understand our user’s workflows and goals.
Creating tasks and procedures that accomplish realworld activities can be quite challenging.
• Determining the tasks to be documented is not always
clear and requires some serious consideration…enter
user research!
Real versus artificial tasks – Example
Using the Address window
Finding an address
To use the Address window:
1. Type the name of the person in the
Name field.
2. If you know the location where the
person works, type it in the Location
field.
3. Optional: Select the Add to my
address book check box to add the
address to your personal book.
4. Click one of the following buttons:
• OK – InfoFinder displays the
address that you requested
• Cancel – The window closes
without finding the address
To find an address:
1. Select Find  Address. The Address
window opens.
2. Type the name of the person in the
Name field.
3. Optional: Select the Add to my address
book check box to add the address to
your personal book.
4. Click OK. InfoFinder finds the address.
Tips for approaching the task
Focus on real
user tasks,
not features
and functions
Start with the
heading
Headings reveal the artificial
A user wants to count the records in a file.
Real task:
Counting Records with the
CNTREC Utility
Artificial Task:
Using the CNTREC Utility
Create headings that reveal the task
•
•
•
•
Headings help users find the info they need
Each heading should reveal the type of information that
the topic contains
• “Authorizations” indicates a conceptual topic
• “Authorize Users” indicates a task topic
Begin with an action verb or gerund
Avoid vague, pseudo-task headings
• e.g., “Understanding,” “Learning,” etc.
• Appears task-oriented when really conceptual
TOC’s reveal the overall task orientation
Functional Based
Task Based
• The “Birthday” Screen
• Adding a birthday to the calendar
• The “Calendar” Feature
• Setting a reminder
• The “Submit” Button
• Changing a birthday
• The “Return to Sender” Screen
• Deleting a birthday
• The “Birthday” Screen
• Creating a calendar
Pick out the REAL task…
• Edit a table
• Using the Table Editor
• Creating Tables
Pick out the REAL task…
•
Edit a table
• Using the Table Editor
• Creating Tables – tricky one, could be a concept disguised
as a task!
What is wrong with this task?
•
Heading is “Using startup parameters”
• Vague gerund “Using”
• What is the user actually doing?
• Who uses parameters?
•
A better heading would be “Changing the start-up
behavior” or “Configuring system start-up”
Tips for approaching the task
Focus on real
user tasks,
not features
and functions
Start with the
heading
Optimize
task structure
Divide tasks into discrete subtasks - chunking
• Real-world tasks are often complex and comprised of
•
multiple subtasks or procedures.
Divide main tasks into smaller sub-tasks to provide usable
step-level info…
• If you provided step-level info for “Writing a News Story,” you’d
•
have 1000s of steps!
Break it down:
•
•
•
•
Researching the material
Drafting an outline
Writing a first draft
Etc.
• Aim for nine or fewer steps per task or subtask.
Be sure to consider tasks relationships
•
•
•
•
What is the proper task sequence?
What are the levels of tasks?
What are the interdependencies?
• Is each task discrete, meaning it can stand alone?
• Subordinate tasks?
• Subtask of more than one task?
Let’s look at an example…
Divide tasks into subtasks - Example
Task Overview - Original
Summary Task - Revision









What can we do to improve this???
Hardware requirements
Software requirements
Applying the latest updates
Stopping Processes
Backing up your Process file
Running the utility for Windows
Running the utility for UNIX
Verifying migration
Setting up a new profile
Divide tasks into subtasks - Example
Task Overview - Original
Summary Task - Revision









1. Ensure you have the correct hardware
and software:
 Hardware requirements
 Software requirements
2. Apply the latest updates.
3. Stop Processes.
4. Back up your Processes file.
5. Run the utility:
 On Windows
 On UNIX
6. Verify the migration.
7. Set up a new profile.
Hardware requirements
Software requirements
Applying the latest updates
Stopping Processes
Backing up your Process file
Running the utility for Windows
Running the utility for UNIX
Verifying migration
Setting up a new profile
Tips for approaching the task
Focus on real
tasks, not
features and
functions
Start with the
heading
Optimize
task structure
Keep task
focus down
to lowest
level step
Continue task-orientation down to the STEP
level
• Task orientation extends to the level of the lowest step.
• Any step not written or ordered correctly can cause user
errors.
• Similar relationship principles apply:
• Organize steps from the user’s perspective.
• Identify when a set of steps are actually a subtask.
• Identify when a step is subordinate to another.
•
Avoid littering the steps with feature spam.
Remember the TW-101 guidelines for writing steps
•
Make each step a clear action for users to take. A step
isn’t complete unless it has an action for the user to do.
•
•
Use active voice.
•
Include an imperative verb in the first sentence of every
step
“In the first column, type the date.”
Use verbs that denote actions the user does versus
actions the product does.
Group steps for improved usability
•
As with grouping subtasks, grouping steps within a
task improves usability.
•
Grouping:
• Helps users relate to the overall task
• Streamlines the task and makes specific steps easier to find
• Indicates relationships between steps
•
Example…
Group steps for improved usability
Original
Revision
To add a setting to your profile:
1. Select the profile you want and right-click.
2. Select Properties from the menu.
3. In the Properties window, find the name of
the profile file.
4. Close the Properties window.
5. Open you profile in a text editor.
6. Add the setting to your profile file in the
settings section.
7. Save the profile.
8. Run the profile command.
To add a setting to your profile:
1. Determine the name of the profile file:
a. Right-click the profile that you want and
select Properties from the menu.
b. In the Properties window, find the name
of the profile file.
2. Update the profile with the new setting:
a. Open you profile in a text editor.
b. Add the setting to your profile file in the
settings section.
c. Save the profile.
3. Run the profile command.
Clearly identify optional and conditional steps
Maintain clarity and conciseness in tasks by carefully consideration
of optional and conditional steps.
Optional steps
• Those that a user can skip and still
complete the task successfully
• Try to avoid including these steps
• If necessary to include, clearly mark
as optional
Conditional steps
• Those that users follow only if certain
criteria apply
• Always start the step with the
condition
• Generally begin with “if”
• Users who meet the criteria must
follow the step
Summary for keeping on track with taskorientation
Keep focus
on REAL
tasks
Use headings
that reveal
the task
Optimize
task structure
Keep task
focus down
to lowest
level step