1. Writing Task-Oriented Documentation
The core of quality end-user documentation

2. 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 ]

3. 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?

4. 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.

5. 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.

6. 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!
Users are generally more computer literate and need less orientation to an unfamiliar computer-based paradigm
Jobs demands result in less willingness or ability by users to invest time to learn
In short, users just want to get things done

7. What now? Tips for approaching the task…
Focus on real user tasks, not features and functions
Perspective when completing a task is different than for contextual Help (e.g. Help on a specific UI screen or control)

8. 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.
Sometimes in our earnest attempts to produce task-oriented doc, we inadvertently come up with artificial tasks.

9. 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.
Creating tasks and procedures that accomplish real- world activities can be quite challenging.
To write truly helpful, task-oriented doc, we need to understand our user’s workflows and goals.
Determining the tasks to be documented is not always clear and requires some serious consideration…enter user research!
In fact, there are computer programs that simulate the basic click patterns through the nav. Paths. Our roles as TCs is bigger, more important than this.
By covering all the click-patterns from top level of navigation down to a place of completion, you may think you are covering all user tasks, but often the real tasks cross over several nav. paths, are comprised of multiple subtasks, and are much more complex than it might seems at first look.

10. Real versus artificial tasks – Example
Using the Address window
Finding an address
To use the Address window:
Type the name of the person in the Name field.
If you know the location where the person works, type it in the Location field.
Optional: Select the Add to my address book check box to add the address to your personal book.
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:
Select Find  Address. The Address window opens.
Click OK. InfoFinder finds the address.
Artificial tasks is not just about the headings
Version 1 never really says what the objective is; no real task
Cancel option is clutter
Include just as much detail as is necessary

11. Tips for approaching the task
Focus on real user tasks, not features and functions
Start with the heading
Perspective when completing a task is different than for contextual Help (e.g. Help on a specific UI screen or control)

12. 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

13. 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
Here's a test. Next time you see a topic with a name like "Understanding the Interface," see whether it actually contains procedural steps for how to "understand," or whether it is just a description of the interface. If the latter, a more accurate heading is simply "The Interface.“
Good headings produce a good table of contents, from which users can accurately predict what they will find in each section, and which do not require any specialized knowledge of the product to recognize.

14. TOC’s reveal the overall task orientation
Functional Based
Task Based
The “Birthday” Screen
The “Calendar” Feature
The “Submit” Button
The “Return to Sender” Screen
Adding a birthday to the calendar
Setting a reminder
Changing a birthday
Deleting a birthday
Creating a calendar

15. Pick out the REAL task… Edit a table Using the Table Editor
Creating Tables
Creating Tables – AMBIGUOUS! Is this a task or a concept?

16. Edit a table Pick out the REAL task… Using the Table Editor
Creating Tables – tricky one, could be a concept disguised as a task!
Creating Tables – AMBIGUOUS! Is this a task or a concept?

17. 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”
"Using startup parameters". Change to "Changing start-up behavior" or something similar. "Using parameters" is an artificial task. Who "uses" parameters? (Actually, it's the software that "uses parameters," isn't it?)

18. Tips for approaching the task
Focus on real user tasks, not features and functions
Start with the heading
Optimize task structure
Perspective when completing a task is different than for contextual Help (e.g. Help on a specific UI screen or control)

19. 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.
Complex tasks tend to be comprised of the simple easily identified, UI procedures

20. 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…

21. Divide tasks into subtasks - Example
Task Overview - Original
Summary Task - Revision
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
What can we do to improve this???
This collection of tasks comprises an overall process for migration to a new version of the software.
What’s wrong with this?
Does not indicate any required order
Not all seem to be tasks.
Does not indicate options or branching where there in fact is.
What can we do this collection of tasks

22. Divide tasks into subtasks - Example
Task Overview - Original
Summary Task - Revision
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
Ensure you have the correct hardware and software:
Apply the latest updates.
Stop Processes.
Back up your Processes file.
Run the utility:
On Windows
On UNIX
Verify the migration.
Set up a new profile.

23. 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
Perspective when completing a task is different than for contextual Help (e.g. Help on a specific UI screen or control)

24. 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.

25. 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.
Use verbs that denote actions the user does versus actions the product does.
Include an imperative verb in the first sentence of every step “In the first column, type the date.”

26. 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…

27. Group steps for improved usability
Original
Revision
To add a setting to your profile:
Select the profile you want and right-click.
Select Properties from the menu.
In the Properties window, find the name of the profile file.
Close the Properties window.
Open you profile in a text editor.
Add the setting to your profile file in the settings section.
Save the profile.
Run the profile command.
Determine the name of the profile file:
Right-click the profile that you want and select Properties from the menu.
Update the profile with the new setting:
V2. shows relationships of some steps to each other, makes it easier to scan. Note that the more usable version is not always shorter!

28. 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

29. Summary for keeping on track with task-orientation
Keep focus on REAL tasks
Use headings that reveal the task
Optimize task structure
Keep task focus down to lowest level step