The Two-Click Mandate: A Case Study
Click a link below to jump to a particular section; click any "
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.
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":
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 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:
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.
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:
With these results, we underlined to management the importance of:
We had management approval to implement new tools and processes. They lent us developers and supported us by:
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:
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):
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:
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.
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.
Figure 2: Field-Level Help
During our progress, we encountered problems that we dealt with by following these writing standards:
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.
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:
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.
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:
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.
Figure 5: Screen-Level Integrated Help
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.
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.
Figure 7: Links to More Information
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.
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:
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.
Figure 10: The Reuse Strategy Applied
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.
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.
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.
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:
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.
Through this 5-year project, we learned many key lessons:
We also found things that helped us:
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:
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.
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 (firstname.lastname@example.org) 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.