Writing Task-Oriented Documentation

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

description

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

Transcript of Writing Task-Oriented Documentation

Page 1: Writing Task-Oriented Documentation

Writing Task-Oriented DocumentationThe core of quality end-user documentation

Page 2: Writing Task-Oriented 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.]

Page 3: Writing Task-Oriented Documentation

A review: the three topic types

describes why and whatConcept•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?

describes how to perform a taskTask•Procedural Typically involves numbered steps •Task steps How do I complete my task? •High-level process What do I do next?

provides details necessary to make decisionsReference

•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?

Page 4: Writing Task-Oriented Documentation

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.

Page 5: Writing Task-Oriented Documentation

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.

Page 6: Writing Task-Oriented Documentation

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!

Page 7: Writing Task-Oriented Documentation

What now? Tips for approaching the task…

Focus on real user tasks, not features

and functions

Page 8: Writing Task-Oriented Documentation

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.

Page 9: Writing Task-Oriented Documentation

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!

Page 10: Writing Task-Oriented Documentation

Real versus artificial tasks – Example

Using the Address window Finding an addressTo 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.

Page 11: Writing Task-Oriented Documentation

Tips for approaching the task

Focus on real user tasks, not features

and functionsStart with the

heading

Page 12: Writing Task-Oriented Documentation

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

Page 13: Writing Task-Oriented Documentation

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

Page 14: Writing Task-Oriented Documentation

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• The “Birthday” Screen

• Adding a birthday to the calendar

• Setting a reminder• Changing a birthday• Deleting a birthday• Creating a calendar

Page 15: Writing Task-Oriented Documentation

Pick out the REAL task…

• Edit a table• Using the Table Editor• Creating Tables

Page 16: Writing Task-Oriented Documentation

Pick out the REAL task…

• Edit a table• Using the Table Editor• Creating Tables – tricky one, could be a

concept disguised as a task!

Page 17: Writing Task-Oriented Documentation

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”

Page 18: Writing Task-Oriented Documentation

Tips for approaching the task

Focus on real user tasks, not features

and functionsStart with the

headingOptimize task

structure

Page 19: Writing Task-Oriented Documentation

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.

Page 20: Writing Task-Oriented Documentation

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…

Page 21: Writing Task-Oriented Documentation

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

Page 22: Writing Task-Oriented Documentation

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

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.

Page 23: Writing Task-Oriented Documentation

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

Page 24: Writing Task-Oriented Documentation

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.

Page 25: Writing Task-Oriented Documentation

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

Page 26: Writing Task-Oriented Documentation

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…

Page 27: Writing Task-Oriented Documentation

Group steps for improved usability

Original RevisionTo 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.

Page 28: Writing Task-Oriented Documentation

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

Page 29: Writing Task-Oriented Documentation

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