Alyssa Fox's presentation slides for the March 20, 2012 STC Houston program meeting.

1. Targeted Documentation
STC Houston Program Meeting
Alyssa Fox
Senior Manager, Information Development
NetIQ Corporation
20 March 2012

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
2 © 2012 NetIQ Corporation. All rights reserved.

3. 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.
3 © 2012 NetIQ Corporation. All rights reserved.

4. 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
4 © 2012 NetIQ Corporation. All rights reserved.

5. 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
5 © 2012 NetIQ Corporation. All rights reserved.

6. 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
6 © 2012 NetIQ Corporation. All rights reserved.

7. 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
7 © 2012 NetIQ Corporation. All rights reserved.

8. 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
8 © 2012 NetIQ Corporation. All rights reserved.

9. 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
9 © 2012 NetIQ Corporation. All rights reserved.

10. Targeted Documentation
Best 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
10 © 2012 NetIQ Corporation. All rights reserved.

11. 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?
11 © 2012 NetIQ Corporation. All rights reserved.

12. 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!
12 © 2012 NetIQ Corporation. All rights reserved.

13. 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.
13 © 2012 NetIQ Corporation. All rights reserved.

14. 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)
14 © 2012 NetIQ Corporation. All rights reserved.

15. 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).
15 © 2012 NetIQ Corporation. All rights reserved.

16. 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.
16 © 2012 NetIQ Corporation. All rights reserved.

17. 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.
17 © 2012 NetIQ Corporation. All rights reserved.

18. Reviewing and Refining the Plan
Questions?
Thank you.
18 © 2012 NetIQ Corporation. All rights reserved.