The Two-Click Mandate: A Case Study

By Karen Lowe

Bookmark and Share


Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Introduction    Link to the review contents

One technical communication team delivered answers to user questions in two clicks with a help file created in DITA XML, using structured writing, different tools and a new information architecture. Content was linked one-to-one with application elements. Hyperlinks in one area of each screen make user access easy. The communicators established a linking strategy, used natural language for guided navigation and developed a reuse strategy involving references instead of duplication of content. The result was delivery of an InfoCenter that's easy to maintain and to expand, which a portion of the team will be doing for the next 20+ years.

The Challenges    Link to the review contents

Every technical communicator wants to deliver relevant information to a user in a timely manner - that is, when the user needs that information. For our team of technical communicators, the goal was encapsulated in the "two-click mandate":

Provide an answer to a user's question in two mouse clicks.

To accomplish this, we moved from a traditional tool to an XML standard to develop a better approach for information delivery. The move included:

  • a shift to structured writing
  • an emphasis on reusing common content
  • a different architecture
  • a different tool and delivery process
  • an increase in the connections between the application and the help

The Situation

A new computer application was a year into development. It was a large project that would meet complex usage needs through a flexible design. Because of the variations built into the application, users would have multiple goals, different starting points and comprehensive needs. To the writers, the project presented an opportunity to start something new and to think outside the traditional box.

Factors affecting the development environment are summarized in the following table:

Environmental Factor Impact to Writers
Methodology (Agile, XP, SCRUM) Fast paced work
Emphasis on communication Writers were included in conversations on functionality and development progress
Nightly code builds Constant change with users wanting to see updated information all the time
Cross-functional development team Writers had access to business users, developers and testers
Growing team Need for continual communication and leveraging work already completed

The entire team swelled to over 40 developers and 90 people in total and was broken into five 'pods' each with deliverable goals per two-week sprint. The writing team grew from one to four people. During this growth, the future of the traditional tool came into question, creating an opportunity for the writers to address their pain-points and find a better way to do things.

The end-users of the application had many needs. They knew their job, but didn't know the application. Also, implementation of the new application would force changes to their work processes. For the writers, this meant that everyone would be searching for information but the paths they choose may be different, depending on their old points of reference. Content, and especially tasks, must be accessible and findable. Whatever structure we used had to allow for growth as the content grew.

The Journey    Link to the review contents

To reach our destination, the team needed to do a lot of ground work and preparation.

We began work on a few different fronts. In this case study, the steps are presented as separate areas but, in fact, they were intricately interconnected. I've used a journey metaphor as a parallel to highlight the various elements needed to come together for us to reach the destination.

Getting Ready to Go

Before you can go anywhere, you have to have an idea of where it is you want to end up. For instance, if you know you want to go to an exotic destination (say, an STC conference in Atlanta), you've got the starting point to plan your trip. In our team's case, we knew that we were going on a journey to a place where the online help worked well with the application because it enabled users to find their answers within two clicks.

That was our destination. But there are other things to consider, especially around the "how" - like what vehicle should we use to get there (how about a car), a method of getting there (like a road - oh, and map would be nice) and the ability to get there (a driver, money for gas, that sort of thing).

We started by crystallizing our vision so we could articulate it to project management to obtain support and approval for spending time to improve our processes.

The Pre-Approved Car Loan: Getting Management Buy-in

Before we could even consider a new approach, we needed to get management support. Since we worked in an Agile environment, management was more willing to take a few chances on a "spike" than they would be in other projects. And because this application (and its help) was in development, we had more flexibility and a bit of time to try new and different things than we would have had in a traditional project.

Consider this stage as obtaining a pre-approved car loan.

For the vehicle itself, we needed to clarify our requirements. We shopped around for something that we could use to single-source the content in manageable, reusable, findable topics and ideally that would allow us to automate as much as possible.

We started with some rudimentary usability testing. Using paper prototypes, one writer asked team members to play the Help Game. This game fit into the project's Agile approach of getting user feedback quickly and incorporating that feedback into the design. And the idea of a 'game' made it easy to find test subjects.

From this usability test, we better understood what users expected to happen when they clicked on various screen elements, what information they would want to find and how they would search for more information. This helped us fine-tune and substantiate our theories and approaches, which help to clarify our vision.

The vision stressed the importance of:

  • integration between the help and the application
  • multiple paths to locate content in the help
  • reusability within the content
  • adapting to changes in development

With these results, we underlined to management the importance of:

  • having one repository of all knowledge about the application. It simplified access to information for the team members and the clients and reduced searching time.
  • satisfying a wide range of user needs by providing a way to find information from both the specific to the general (field-level questions opened the help where the user could find more information) as well as from the general to the specific (open the entire file with a question and drill down to specific information)
  • enabling the writers to quickly adapt to changes in the application, so the content was constantly up-to-date. This helped the writers keep pace with the developers.
  • providing consistent and quality content to create goodwill for the company and enhance the company's reputation

We had management approval to implement new tools and processes. They lent us developers and supported us by:

  • including the help impacts in the story template
  • enforcing standard links between the application and the help with the development team
  • having testers verify the help links (and the help content) while they tested the application

With management support, we embarked on the next stage: development of a close connection to the application. It felt like we were headed to the car lot for a purchase.

The Car: DITA

Now that we knew where we wanted to go, we had to find a vehicle to get us there. We shopped around and decided that we needed something to meet our immediate and future needs, which included:

  • a modular way to reuse common content in one project by reference, not by copy and paste - similar to object-oriented programming
  • a single source of specific content that, when updated, would take immediate effect in all areas of the help
  • a way to create multiple outputs that contain different topic sets from one source of content
  • a way to reuse content between projects in the company
  • a tool that would be around for at least 20 years (proprietary tools weren't an advantage with the project team that embraced open source tools)

The primary output we wanted to deliver was an Eclipse InfoCenter help file because it freely provided (that is, with no purchase of tools and no code development required):

  • Navigation features for users
  • Integrated Search functionality
  • Bookmarks and other integrated aids
  • Clean (standard) HTML topics for integration with the application

The choice that rose to the top was Darwin Information Typing Architecture (DITA). With the DITA open toolkit (DITA-OT), we could produce clean, readable HTML output on any platform and InfoCenter help. Our developers already used the Eclipse SDK and were familiar with XML editing tools and the output. These were tools we could leverage in our implementation.

DITA was extensible and adaptable. By separating content from its delivery, the writers could focus on creating accurate content, not fuss over the look of the output. Our technical specialist took care of that through style sheets.

DITA arose as a natural fit. We knew that moving to structured authoring and to DITA were major technical undertakings, but the team was excited. We could see the value of the destination in our mind's eye. We sat behind the wheel of this new vehicle, anxious to drive off into the sunset.

The CAA (or AAA): Our Structure

Now that we had a way to get somewhere, we need to protect ourselves by providing a structure around our efforts. Like getting insurance and roadmaps for that new car, we needed some sort of framework that would grow with us and guide us on our journey.

After a search for help around information architecture, we found John O'Gorman and Tiberon Information Architects (via STC chapter query). He said: "I caution my clients that structured authoring techniques are only part of the solution for companies looking to make their content more accessible." Our thoughts exactly!

He analyzed our information and helped us distill it to the essentials. He described delivery of that content in a framework that was:

  • accessible
  • extensible
  • logical

With his help and our analysis, the team of technical communicators developed a mapping strategy that fit with a framework and enabled us to connect the help with the application. He helped direct our efforts by guiding us towards naming conventions and standards for the content.

We felt prepared enough to jump in the car and head off down the open road!

The Road: Connecting the Application and Help

The open road is full of choices - and the application we were documenting had many elements to it.

To make connections between the two, we created a content equivalent in the help for everything in the application - every field and screen. With these topic one-to-one equivalents, developers could easily connect the help elements to the application elements. We standardized this by consistently using a naming convention for each of these elements so it was easy for every developer (40+ different people) to insert the right code for the link to work. As a result, our information development coincided with code development and after each nightly build (one for the code and one for the help), all the pieces fit together.

Screen Elements

Figure 1: Screen Elements

Every field topic started with fld_ and was titled exactly as the application. If the user has a question about a field, the relevant help topic should answer that question in ONE CLICK.

Field-Level Help

Figure 2: Field-Level Help

During our progress, we encountered problems that we dealt with by following these writing standards:

  • If a field with the same name is used on different screens, we kept the same help topic but used a standard table explaining the different uses for each screen. If the usage in each instance matched, we kept the topic generic enough so it applied to both.
  • We used DITA reference topics, which enforced a structure.
  • If applicable, we included specific information about required prerequisite conditions for the field to appear in the application as well as the repercussions of selecting one value/option over another.

To link the application fields to the help topic, the developers added a call with every screen label they created. The calls accessed a mapping file that was accessible by developers and writers for maintenance. As long as the developer included the call to some HTML file, the writer could tweak the mapping file so the correct help topic appeared. This gave the writer control over the application connection, which was helpful if/when the screen label changed.

Mapping File

Figure 3: Mapping File

We then moved to the screens. They were like the superhighways - lots of on and off ramps, twists and turns or, in our case, more user questions. We narrowed down the scope of our questions pertaining to each screen to generic questions around:

  • concepts about the screen (what is this?)
  • tasks to do on the screen (how do I ?)
  • reference information about this screen

Enter the DITA topic types - concepts, tasks, references. We created one topic of each type for every screen, following a standard naming convention. The application linked every screen with each of the three topics, so a user with any of these questions could find an answer in ONE CLICK.

For screen-level links, the calls from the application were more complex. To start with, the User Interface designers designated a portion of the screen to be the help area. This provided a consistent location for the user to go when they need answers. In this location, we placed links to the entire help file (called the Knowledge Base) as well as links to specific screen-related concepts, tasks and reference topics.

Accessing the Entire Help File

Figure 4: Accessing the Entire Help File

To facilitate these screen-related links, the application's screen name was linked to an HTML file made up of:

  • the appropriate prefix
  • the screen name
  • the .html extension

This was where our naming convention was essential in standardizing the application links to the help. Every concept for a screen started with ovr_ (overview), every task started with hdi_ (how do I) and every reference started with sgd_ (screen guide). The name of the screen matched the screen/tab name in the application.

Screen-Level Integrated Help

Figure 5: Screen-Level Integrated Help

Naming Conventions

Figure 6: Naming Conventions

But what about the alternate routes? Users need more information that doesn't necessarily link directly with the application. For these topics, we developed specific topics to answer specific questions and we established a naming convention. We named the topic as specific as we could, using common prefixes based on the topic types. For instance, we created general concept topics that were titled About XYZ. For this file name, we concatenated the prefix abt_ with the subject of the topic. For tasks, we used a tsk_ prefix and for references, we used ref_.

The result was a predictable way for writers to locate topics in the now growing project file.

We had our car, our protection, our maps and a road to drive on. Now we had to overcome other issues that we encountered on our travels.

Other Issues    Link to the review contents

On any trip, bumps along the way can end up being some of the most interesting times. During our project, we learned valuable lessons in our two-click trip.

Crossing Rivers: Linking Content

One question always leads to another, just as a bridge opens up travel to the other side of a river. To give users quick access to related, relevant information, we devised a comprehensive linking strategy. The goal was to satisfy deeper user queries and to facilitate searches through connected content. The strategy helped us create a consistent set of links for each topic. As a result, users can quickly locate more information, if/when required = ONE OR TWO CLICKS.

Link management is a separate task from content creation. We managed all the links through standard DITA relationship tables, not the individual content topics. In the output, the links are controlled by a style sheet, base in the topic type. We used a colour-coded approach to make these types visually distinct. Our user community liked the consistent placement of the links and the colour-coded approach. They used links 86% of the time they were in the help, like they were web surfing for more information.

For the linking structure, we linked the three types of DITA topics for each screen. We also connected the field topics and the screen(s) they appeared on so each field linked back to its screen guide and the screen guide listed each field.

Links to More Information

Figure 7: Links to More Information

Field Topics in a Screen Guide Topic via a DITAmap

Figure 8: Field Topics in a Screen Guide Topic via a DITAmap

Outside of the standard links, we connected other topics using relationship tables. Our analysis and interaction with business users on the team helped us define potential user questions and relevant subject areas. We consolidated the subject areas in a relationship table (nicknamed the Big Hummer). Here, writers simply add the topic in the correct row for the topic to automatically pick up the other links for that subject area.

For example, a topic on allocations (abt_allocations.xml) is added to the allocations section, which includes all links to the other allocation topics.

Allocations in the Big Hummer

Figure 9: Allocations in the Big Hummer

With this structure established, the links were easy to create and maintain. The technical communicators used the structure without noticing it, like a bridge you cross so often you forget it's there.

The Gas: Reusing Content

As the project got bigger and more complex, the technical communicators needed to continually refuel and recharge the content. Our reuse strategy and the power it gave us were as essential to us keeping our sanity as gas is to driving a car.

Change and content overlap was a large reality in this project. To cope with things that changed and were repeated, we developed a strategy for referencing content. By writing targeted, reusable pieces of information, we leveraged a low granularity level, right down to a phrase element. This single-source solution reduced duplication and helped keep information up-to-date.

The overriding vision was: use one source for a content chunk that occurs in more than one location. When the content changed, simply change that one location and rebuild. In DITA, we made extensive use of conrefs at many element levels, especially for:

  • User Interface Components (screen names, field names and buttons)
  • Navigation paths
  • System-defined code values
  • Government agencies

For example, field names on the application changed sometimes daily. We conref-ed the field name instead of retyping it. Also, we added an attribute to the source that enabled a style sheet to control how the field name looked in the output. The result was a consistent output.

The Reuse Strategy Applied

Figure 10: The Reuse Strategy Applied

Happy Dance

The first time this method enabled us to quickly and painlessly cope with a UI change, you should have seen the Happy Dance!

Another thing we learned was to keep our reusable elements in one spot. Early in the project, we learned that conref'ing between topics quickly degrades into an intertangled, cross-reference nightmare, resembling a plate of spaghetti. We soon outlawed spaghetti-code.

No Spaghetti Code

To avoid untangling the pasta situation, we established a rule to conref any reusable item from a specific topic, which started with an RU_ prefix. These ru_ topics were named for functional areas or screens to make content location easier for the writers. For example, if a <p> element is shared between two Process screens, the original content is in a topic called ru_process.xml.

We reused phrases (such as application names), paragraphs (such as security settings), sections (such as business rules) and task steps (such as "click save and check for errors"). Some topics were made up entirely of conrefs. To maintain these topics, writers simply changed content in the ru_ topic (after checking that the changes made sense in all usage instances). We found reuse to be one of the most powerful advantages of DITA. It gave us the fuel we needed to reach our destination.

Sign Posts: Navigation

Over the four years in development, the project blossomed and the help file now includes over 2400 unique topics. To point to information areas, we used guided navigation to direct users, much like road signs signal areas on your trip.

With the volume of information in the help, guided navigation was required, especially for users who wanted to start with the big picture and drill down into the content to find specific information. This "progressive disclosure" approach had to be logical and intuitive for our users.

To start, we broke the contents into the highest level - books based on tasks, concepts and references. Our users' main questions revolved around tasks so the How To book came first on the list. The second most common type of questions center on concepts in the application; hence the What Is book came second. Reference information around the screens came lower on the contents list because most users accessed screen-specific information via the application itself.

Main Books of the Contents

Figure 11: Main Books of the Contents

Once in the help file with a question in mind, the user can drill into the content following the sentence's structure. A user question might be: What is a battery? Or How do I allocate excess gas plant water? For the first question, the user clicks "What is" and then "Battery" and gets information = TWO CLICKS.

If the question is more specific, more clicks are needed. For example, the question "what is battery group processing all about?" requires the user to click What is > Battery > Group Processing = THREE CLICKS.

NOTE: Everyone involved in the project agreed that, although two clicks was the target, if the user has a more specific and precise question, more clicks will be required.

Drilling into the 'What Is' Book

Figure 12: Drilling into the "What Is" Book

Our user survey found that less than half (43%) used the Contents to access information. More commonly used were the Search (93%) and the links at the bottom of each topic (87%). As a result, the increased number of clicks to find specific information via the Contents was less of a concern to the team than closer integration with the application.

The other books in the Contents contain information requested by the project team and users. A glossary contains unique terms used in the application. The Orientation section contains very high level information and e-Learning multimedia topics (e-Training). Finally, the PAS Project book contains license information for third party tools and a topic about the project team.

The help file grew into a "super-sized" version, so we changed its name to Knowledge Base. In the end, we included:

  • InfoCenter content
  • PDF content of specific content areas
  • links to external content (Excel spreadsheets, PDF files and web content)
  • training videos and screen demos (e-Training)
  • glossary of new terms or industry terms that were used differently by the application
  • an optional solution to merge client-specific content with released content so client companies could keep all their application information in one location. For example, the company-specific naming conventions were included with the topics on how to set up that master file.
Client Custom Content

Figure 13: Client Custom Content

The Contents in the help acts as collection of sign posts that point out relevant information to our users. For more GPS-like navigation, our users consult the Search functionality in the InfoCenter layout.

The Destination    Link to the review contents

Through this 5-year project, we learned many key lessons:

  1. Develop and clearly articulate a vision of the end product that supports a valid business goal. With this, it was easy to get management buy-in to support our endeavours.
  2. Know your users. Do all you can to figure out what questions users might have and at which points in the use of the application they might need information. Make the connections at those points and your users will use the help.
  3. Write in a generic, minimalist way in small topic chunks so you can reuse content. Don't waste your time by rephrasing information already written because it only undermines consistency.
  4. Pay attention to your pain-points. Once you identify them, see if there's a strategy that might alleviate them, such as reuse, automation, the use of relationship tables. Ask other people - writers, developers, etc. for suggestions.
  5. Know your information. Break it into its components to identify relationships and then classify it based on logic employed by your users. Establish an information model that can help you work within the structure.
  6. Validate your conclusions to confirm your assumptions and your approach. We found that field-level links were our users' the most common entry point into the help application. This finding helped us support the granular level of DITA topics and the extensive connections between the application and the help.

We also found things that helped us:

  • working in an Agile environment, which gave us access to users and helped facilitate instant feedback and clarification
  • keeping the development implementation process as simple as possible via standard naming conventions, which helped get development to make the connections
  • promoting our efforts within the team and with the end-users as often as possible - within teams, at project meetings and user-group meetings. The more people used the help and gave us feedback, the better we could make it.

Bottom Line(s):

Our users are very pleased with the help. Our usability survey indicated that two-thirds of the users would use the help before asking another user for help (which, for this community, is the standard approach to finding out information).

We measured our success by our ability to:

  • enable users to find relevant information to a question within two mouse clicks, through accurate and applicable content for any stage of product usage
  • integrate the help and the application in a seamless, consistent manner
  • allow for a variety of navigation methods that did not add cognitive overload to the users
Our users told us that the help file:
  • contains relevant content - information in one click and 97% of users surveyed thought the content was helpful and thorough
  • is accessible - information in one click from the application, with most users accessing help from field-level links and 87% of users said that once they're in the Knowledge Base, they use the topic links to locate more specific info
  • is easy to use - information follows natural language, which leads to finding answers

Overall, we have achieved on 80% satisfaction rating from users who don't normally access online information. Our users tell us that over 90% of first-time application users start with the Knowledge Base to learn the application, especially if no classroom training is available.

Conclusion 1: Make the help good so that when people consult it, they'll come back to it.
Conclusion 2: Accuracy and thoroughness of content are extraordinarily important to users.

The writers found the approach so successful that we adopted it for all other application help files. We like the repeatable processes, standard architecture and the predictability of maintenance. The avoidance of repetition is contagious and we're investigating ways to leverage more content.

Conclusion 3: Although the shift to DITA seemed daunting, the payoffs in writer satisfaction were easy to realize.

Management likes the approach we're using. The standardization and consistency payoffs suit the company direction. The efficiencies we're realizing support the company bottom line. The sales team who demonstrate the product say that the Knowledge Base is "scary good" (which we take as being positive).

Conclusion 4: Show how the vision matches the company vision and management support will follow.

We arrived at our destination - an accurate help file that provides answers to user questions within two clicks. The trip wasn't 100% smooth, but the results were worth it.

The journey continues: Release 7 is due out in June.


Karen Lowe ( is a senior STC member in the Alberta Chapter. She has worked in communications over 20 years, in multiple fields including banking, health care insurance and interactive hardware. She currently works in the Canadian oil and gas industry in Calgary, Alberta.

Karen Lowe
Team Lead, Technical Communications
900 800 5th Ave. SW
Calgary, Alberta, T2P 3T6, CANADA


Copyright © WinWriters, Inc. All Rights Reserved.
shannonm *at* writersua *dot* com
Last modified on