Targeted documentation STC Houston, Mar 20, 2012
•Download as PPTX, PDF•
0 likes•479 views
The document discusses the principles and goals of targeted documentation. It advocates writing less but better documentation that focuses on the essential information users need to achieve their goals. It emphasizes understanding users and their needs in order to provide the right content in the right format. The document provides guidance on techniques for targeted documentation including conducting a thorough task analysis, focusing on the most common tasks, and designing documentation around user goals rather than product features.
Report
Share
Targeted documentation STC Houston, Mar 20, 2012
- 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.