targeted documentation stc houston, mar 20, 2012

Targeted DocumentationSTC Houston Program Meeting

Alyssa Fox

Senior Manager, Information Development

NetIQ Corporation

20 March 2012

© 2012 NetIQ Corporation. All rights reserved.2

Minimalist Documentation Tenets

• Understand the audience.

• Create realistic content.

• Build basic, minimal, useful documentation.

• Provide the right information in the right format at the right time so users can make the right decisions.

• Write less, write better.

~ Bernard Aschwanden, Publishing Smarter


Targeted Documentation Goals

• Provide positive user experience with products.

• Provide sufficient information for customers to use our products effectively to achieve their goals.

• Provide high-quality documentation based on understanding our users and their content and format needs.

• Improve product GUIs so they:– Are as simple to use as possible

– Are easy to figure out (self-discoverable)

– Require less documentation

• Effectively use “new normal” resource numbers.


Anticipated Benefits

• Clearer content

• Easier reuse

• More effective use of resources

• Reduced costs for maintenance and translation

• Improved quality

• Fewer Tech Support calls

• Better user experience

• Happier audience


Traditional Documentation

• Values comprehensiveness

• Values consistency

• Steps users through everything in the GUI

• Sometimes tries to compensate for bad GUI design

• As a result, aims at the least-skilled users


Targeted Documentation

• Requires solid knowledge of users, their needs, and use cases

• Follows CPR writing style

• Provides specific information when and where necessary

• Provides big picture tasks and workflow

• Documents tasks with gotchas you need to know to be successful

• Documents best practices

• Provides extensive and relevant examples

• Provides troubleshooting information

• Does not document the obvious or the easily discoverable


Users as Decision Makers

“One of my aha! moments came during a usability test of the online help I had written for a predictive dialer—a device that dials phone numbers automatically then, if someone answers, connects that person with the first available call-center agent. On one of the screens, administrators were to set the Busy Callback Time, which I had defined as “the time the dialer waits before redialing a line that is busy.” I had specified the minimum and maximum allowed values—0 and 999 minutes, respectively—and even mentioned that users could click an up arrow to increase the value; a down arrow to decrease the value. And, of course, I also told users to click Save to save their changes. When I tested the online help in a usability lab, I was delighted to see that users actually opened the help topic I had written for that screen. But when the users started reading my help, I learned the following:

• The label Busy Callback Time was self explanatory — everybody got it right away.

• No one wanted to set the value to less than zero. (Apparently time travel buffs don’t work in call centers.)

• No one tried to set a value that was even close to going over the allowed maximum and, if someone had, the system would not have accepted the value.

• Everyone figured out the up and down arrows without my help.

• They figured out the Save button on their own, too.

In the end, users went to the online help with one simple question: “What’s a good number of minutes to delay before calling back?” It seems that was the only thing I had not documented.”

~ Michael Hughes, Intercom, February 2009


Writing Style & Documentation Format

• Style guide

• Writing for translation and ESL

• Templates

• Topic-based writing

• Books converted to Help (single-sourcing)

• Books available in PDF and HTML

• Context-sensitive Help in addition to converted topics

• Web-hosted documentation

• User assistance in GUI


Content Design

• Installation – comprehensive

• Configuration – comprehensive

• Usage (tasks/procedures) – targeted

– Perform task analysis.

– Determine how obvious the GUI is around that task.

– Fix the GUI first!

• Concepts/best practices – targeted

• Reference – targeted

• Troubleshooting – comprehensive


Targeted DocumentationBest Practices• Start with the minimum information a user needs.

• Provide what the user needs to know, not what you know.

• Describe why you would use a feature or perform a task with the software, and relate that information back to users’ goals.

• Add graphics, screenshots, and demos where relevant and useful.

• Assume the user has knowledge appropriate for their jobs.

• Let the UI speak for itself, and don’t repeat the obvious.

• Title topics in a meaningful way – Developing a Database Maintenance Strategy vs. Using the XYZ Tab.

• Get out of book-mode.

– “My brain is stuck in book-mode. I figure it’s going to take my brain a while to stop thinking linearly. I must consciously think of what information a user needs to solve the problem at hand and no more.”

~ Patty Blount


User Experience

• Usability testing

• Assistance with GUI wording and screen flow for developers

• Guidelines for error messages

• Usability bugs

• Pushback on fixing GUI problems with documentation

How can we improve the GUI so that less doc is required?

How can we design new GUIs or Help systems so every window doesn’t require a Help topic?


Evangelizing Targeted Documentation

• Understand that this approach is a change.

• Be prepared for varied reactions from your project team.

• Ensure you can support your decisions to those who don’t understand what you’re doing.

• Gain buy-in from your user advocates and project teams.

• Keep in mind the big picture goals.

• Recognize that this change will not happen overnight.

• Communicate, communicate, communicate!


Defining Your Users

• Continually clarify user descriptions, personas, and use cases.

– User definition meetings with user advocates (product managers, Tech Support, field)

– Customer forums

– Tech Support sessions

– Sprint demos

– User conferences

– User comments on online documentation

• Developers, testers, writers: You are not your user.


Defining Top Tasks

• What problems does this product or solution solve for our users?

• What are the core tasks the user wants to accomplish?

– What are the essential tasks? (modified task analysis)

– What are important but non-essential tasks? (not top priority)

– What top user goals can we base our core tasks on (not based on product features)?

– What tasks are discoverable by the user? (don’t document)


Conducting a Task Analysis

• “A thorough task analysis is the route to minimalist publications…” JoAnn Hackos, Managing Your Documentation Projects

• Document tasks from the user perspective, not the GUI perspective.

– What did the customer buy our software to provide?

– What are the most common use cases?

– What are our users’ goals?

– How does our software get our users to their goals?

• Provide big picture overviews: “Lifecycle of an Alert”.

• Create workflow tasks from the user perspective.

• Do not mimic the product’s structure (such as documenting menus from left to right).


Building the Plan

• Ensure you address main areas cited by users:– Planning

– Installation and configuration

– Top tasks

– Troubleshooting

• Work usability testing into your plan.

• Determine what existing source material fits into your new plan, what needs to be rewritten, and what outdated or obvious information you can remove.

• Don’t build the plan based on current books or help structure.


Reviewing and Refining the Plan

• Review your plan with your manager to gather feedback on documentation organization and content.

• Review your plan with project stakeholders to ensure the plan addresses top user needs.

• Incorporate feedback into the plan.

• Create a schedule for incrementally building targeted documentation into existing documentation libraries over multiple releases.


Thank you.

Reviewing and Refining the Plan

Questions?

targeted documentation stc houston, mar 20, 2012

Technology

targeted documentation

users goals

useful documentation

right information

user needs

highquality documentation

online help

troubleshooting information