Revised User Guide

Turning product-focused text into user-focused tasks and FAQs using industry standard software

I evaluated the existing user guide with usability heuristics and rewrote the guide in a simpler, cleaner style with the lead writer. Working in Adobe FrameMaker, we split the original user guide into three smaller guides, each focused on a specific user group. We prioritized the guide for data managers because we had limited time for this release. Within that guide, I changed the organization of the procedures to better match the users’ workflow, eliminated unnecessary conceptual information, and rewrote some conceptual information into FAQs.

The newest release for this product is not available to the public yet.

Revised Procedures

The procedures in the original user guide were organized by the pages in the product’s user interface (UI), rather than the actual users’ workflows. The procedure titles used the UI’s language rather than the users’. Many procedures also included lengthy introductory information before they began. While testing the original guide, I also discovered that naviagtion steps were missing from the beginning of procedures. New users had no way of knowing how to get where they needed to be in the UI because the context-sensitive help never included navigational information.

To tailor these procedures to users’ needs, I rewrote most of the titles and removed almost all conceptual information from before or within the procedures. At the beginning of every procedure, I included navigational steps. Users can now reach the correct place in the UI to begin their task regardless of where they started. Working within the time constraints to meet the release date, we revised the procedures to meet users’ needs, while knowing that further revision is still necessary. Our next step is to evaluate the field descriptions and determine where we can leave them out and where users actually need them.

Click the images on the right to expand the before and after example procedures. The revised procedures aren’t formatted for HTML because the product hasn’t been released yet.

If you’re interested in more examples of my procedures, check out my first generation user guide. Or if you’d like to see how I turned some of these procedure into short videos, take a look at my video script.




When I removed the conceptual information from the procedures in the original user guide, I had to decide what to do with it. First, did my users need this information at all? If the answer was “probably not,” I took it out. If the answer was “They might, given the right circumstances,” I rewrote it as a user-focused FAQ. Including only the information my users need to know is a pillar of useful technical writing.

At the end of each chapter, I placed FAQs written from the users’ perspective. Instead of asking “What are flags?” which is very product-focused, I stepped into the users’ shoes and tried to ask what they might ask while doing their jobs, like “Can I use multiple flags on a single data item?” I then answered their question as directly as possible, and sometimes gave additional information that could be useful.

Click the images on the right to expand the conceptual example and its’ revised FAQs. The revised procedures aren’t formatted for HTML because the product hasn’t been released yet.

If you’d like to see more about how I turned conceptual information into useful user-focused topics, check out my first generation user guide.