Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Targeted documentation


Published on

Published in: Business, Technology
  • Be the first to comment

  • Be the first to like this

Targeted documentation

  1. 1. Targeted DocumentationAlyssa FoxDirector, Information DevelopmentNetIQ Corporation
  2. 2. © 2012 NetIQ Corporation. All rights reserved.2Minimalist Documentation Tenets• Understand the audience.• Create realistic content.• Build basic, minimal, useful documentation.• Provide the right information in the right format at theright time so users can make the right decisions.• Write less, write better.~ Bernard Aschwanden, Publishing Smarter
  3. 3. © 2012 NetIQ Corporation. All rights reserved.3Targeted Documentation Goals• Provide positive user experience with products.• Provide sufficient information for customers to use ourproducts effectively to achieve their goals.• Provide high-quality documentation based onunderstanding our users and their content and formatneeds.• 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.
  4. 4. © 2012 NetIQ Corporation. All rights reserved.4Anticipated 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
  5. 5. © 2012 NetIQ Corporation. All rights reserved.5Traditional 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
  6. 6. © 2012 NetIQ Corporation. All rights reserved.6Targeted 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 besuccessful• Documents best practices• Provides extensive and relevant examples• Provides troubleshooting information• Does not document the obvious or the easily discoverable
  7. 7. © 2012 NetIQ Corporation. All rights reserved.7Users as Decision Makers―One of my aha! moments came during a usability test of the online help I had written for a predictive dialer—adevice that dials phone numbers automatically then, if someone answers, connects that person with the firstavailable call-center agent. On one of the screens, administrators were to set the Busy Callback Time, which Ihad defined as ―the time the dialer waits before redialing a line that is busy.‖ I had specified the minimum andmaximum allowed values—0 and 999 minutes, respectively—and even mentioned that users could click anup arrow to increase the value; a down arrow to decrease the value. And, of course, I also told users to clickSave to save their changes. When I tested the online help in a usability lab, I was delighted to see that usersactually opened the help topic I had written for that screen. But when the users started reading my help, Ilearned 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 callcenters.)• No one tried to set a value that was even close to going over the allowed maximum and, if someonehad, 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 ofminutes to delay before calling back?” It seems that was the only thing I had not documented.”~ Michael Hughes, Intercom, February 2009
  8. 8. © 2012 NetIQ Corporation. All rights reserved.8Writing 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
  9. 9. © 2012 NetIQ Corporation. All rights reserved.9Content 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
  10. 10. © 2012 NetIQ Corporation. All rights reserved.10Targeted 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 thesoftware, 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 DatabaseMaintenance 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 stopthinking linearly. I must consciously think of what information a user needs to solve theproblem at hand and no more.‖~ Patty Blount
  11. 11. © 2012 NetIQ Corporation. All rights reserved.11User Experience• Usability testing• Assistance with GUI wording and screen flow for developers• Guidelines for error messages• Usability bugs• Pushback on fixing GUI problems with documentationHow can we improve the GUI so that less doc is required?How can we design new GUIs or Help systems so every windowdoesn’t require a Help topic?
  12. 12. © 2012 NetIQ Corporation. All rights reserved.12Evangelizing Targeted Documentation• Understand that this approach is a change.• Be prepared for varied reactions from your projectteam.• Ensure you can support your decisions to those whodon’t understand what you’re doing.• Gain buy-in from your user advocates and projectteams.• Keep in mind the big picture goals.• Recognize that this change will not happen overnight.• Communicate, communicate, communicate!
  13. 13. © 2012 NetIQ Corporation. All rights reserved.13Defining Your Users• Continually clarify user descriptions, personas, anduse cases.– User definition meetings with user advocates (productmanagers, 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.
  14. 14. © 2012 NetIQ Corporation. All rights reserved.14Defining Top Tasks• What problems does this product or solution solve forour users?• What are the core tasks the user wants toaccomplish?– 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 (notbased on product features)?– What tasks are discoverable by the user? (don’t document)
  15. 15. © 2012 NetIQ Corporation. All rights reserved.15Conducting a Task Analysis• ―A thorough task analysis is the route to minimalist publications…‖ JoAnnHackos, 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 fromleft to right).
  16. 16. © 2012 NetIQ Corporation. All rights reserved.16Building 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 yournew plan, what needs to be rewritten, and whatoutdated or obvious information you can remove.• Don’t build the plan based on current books or helpstructure.
  17. 17. © 2012 NetIQ Corporation. All rights reserved.17Reviewing and Refining the Plan• Review your plan with your manager to gatherfeedback on documentation organization and content.• Review your plan with project stakeholders to ensurethe plan addresses top user needs.• Incorporate feedback into the plan.• Create a schedule for incrementally building targeteddocumentation into existing documentation librariesover multiple releases.
  18. 18. © 2012 NetIQ Corporation. All rights reserved.18Thank you.Reviewing and Refining the PlanQuestions?