April 2011

Road to Change

CIDMIconNewsletterTodd Herrick, Symitar, a JHA Company

I am a technical writer for the credit union division of a data-processing software company. We have provided extensive product documentation to our clients for over 25 years. In that time, many changes have occurred in both content and format. One of the greatest changes was moving from text-based documentation to interactive, HTML-based documentation. Most recently, we have been working on incorporating Darwin Information Typing Architecture (DITA) standards and XML into our documentation. Because we have over 3500 documents already, the change has been a slow and carefully planned process, and not all the changes we are making are perfect.

I consider myself a detailed-oriented design freak. Having worked summers as a surveyor’s assistant for the Alaska Highways Department when I was in college, it occurred to me that some of the challenges we face in our documentation redesign can be compared to the challenges road builders face when designing roadways. In this article, I use the road-building analogy to describe several observations and solutions I used to meet those challenges.

State of Manydocsnia Map

In our state of Manydocsnia, we have many different towns with their own ideas (departments), plans (procedures), and cultures (styles). They are scattered around the state in random order (identified by numbers and letters), illustrated in Figure 1.


Figure 1: State of Manydocsnia

As long as no one ever travels or wants to trade with another town, people can pursue their own plans as they like. However, a community cannot survive without trade and customers for their products, so the Governor of Manydocsnia has decided to build roads to connect these disparate communities. The state has devised many plans, each with its advantages and disadvantages.

One Long Road

The first idea is to connect the towns with one long road that starts at 0 and ends at z. It goes through every town, in the easiest geographic order, as shown in Figure 2.


Figure 2: Connecting with one long road

Documentation Advantages

Like the single connecting road, documents can be strung together linearly. Linear organization is typical of a hastily thrown-together document. It is arranged simply and allows access to all ideas. The linear design means the progression of the topics is somewhat dependent on the order in which they are received, rather than on the importance of the content. Linear design can be improved by a table of contents or indices, but these require building additional links to the information.

Documentation Disadvantages

Typically, text documents are designed, written, printed, and distributed. Maintenance is costly, requiring writers to research, redesign, rewrite, and update the materials. Additionally, changes may affect the paths of other documents. Updates are difficult to incorporate, and often users don’t receive them. When users find specific information difficult or that the updates are out of date, they ignore the documentation.

Many Roads

The Governor realizes Manydocsnia needs more than one continuous linear route through the state, and he approves a plan to build more roads. In this plan, each town is connected to many other towns with a complex road system (Figure 3).


Figure 3: Many Roads

Construction begins with great abandon.

Documentation Advantages

Connecting every town via roads is similar to typical interactive documentation using links from one document to almost every other document. Creating many links is relatively simple in HTML and quickly provides a vast amount of information to the user. This method can be effective and user-friendly if you place the links strategically. Users can jump to another document for additional details about a topic and then easily return to where they started; conversely, users who don’t want more information can ignore the link. In this way, it is easy to adjust the level of documentation to the level of experience. When presented in a package, such as a Compiled Help Module (CHM), an interactive table of contents and a search feature provide a “map” for quickly finding a specific topic of interest.

Documentation Disadvantages

Having many links is difficult to maintain because links are broken when individual documents are moved. Documents may be moved frequently as reorganization occurs. Broken links require that the writer find the broken link, find the document that was moved, and fix or remove the link. Additionally, when adding new documents, writers can find it difficult to locate the information they want to link to, especially if there are many documents. Writers may duplicate content if they can’t link to it, which leads to repeated information in multiple documents. When the information must be updated, duplications must be located and changed individually—a tedious and time-consuming activity. These difficulties can be alleviated somewhat by thoughtfully organizing source document locations.

Not So Many Roads

After the flurry of road building, the governor realizes that some of the roads are unnecessary. He forms a committee to study road minimalization. After the committee deliberates (which can take a while—you know committees), they task the highway department with removing the unnecessary roads. The governor worries about removing important roads, so he asks the committee to determine which towns are population centers. After careful study (more time), the committee determines which towns get the most traffic. Reducing roads and identifying heavy traffic towns results in Figure 4 (the larger the dot, the more traffic).


Figure 4: Identify Major Areas;
Minimalize Links

Documentation Advantages

Refining the road system is comparable to the application of DITA standards to existing documentation. Applying these standards reduces maintenance time and can reduce user frustration with broken links. Compared with the example in Figure 3, the table of contents is also simpler. Once the writers reach consensus on what needs to be removed (valid minimalization), they can strategically place links based on specific criteria (for instance, when a document is a task, concept, reference, and so on). This process can be simple or complex depending on the amount of cross-referencing previously done. Users can still jump from one document to another, but now the choices are clearer. You can create policies and procedures for linking documents that can be continued through the rest of the documentation, including newly added documents.

Documentation Disadvantages

Determining major topics can be difficult. You may require user polls or surveys to determine which information is more important or accessed more often. Keep your eyes open for problems regarding what is necessary and what is not. Consensus among writers is essential so that important links are not deleted. Although you don’t necessarily need to change document organization, you may have to extensively revise the table of contents to put important ideas at the top. Removing links can be a complex fix if there are many cross-references; you have to find all references to the removed links. With today’s modern writing applications, you can expedite this process using a carefully crafted search string.

Extreme Minimalism

A sub-group within the state committee is alarmed by all the road building and suggests that they eliminate all roads except those to the busiest population centers. They state, “No one needs to go to those small communities anyway, and we’ll save a lot of time and money if we don’t have to maintain every little street!” Their proposed map looks something like Figure 5.


Figure 5: Extreme Minimalism

Documentation Advantages

Extreme minimalism is a drastic measure for road systems and also for documentation. This plan reduces the time and effort needed to maintain the documentation. Reducing the effort required may, however, also reduce the staffing requirements which might not appeal to the writers.

Documentation Disadvantages

Extreme minimalism is a typical misapplication of the DITA minimalism process. Often people who say, “They don’t need to know this,” aren’t considering the small number of users who need the more specific information. Missing information can lead to gaps in understanding, and, eventually, users may stop referring to documentation and rely more on customer service. You may have to replace removed or lost information later. Also, with reduced effort you may reduce staff. Staff reduction can lead to the loss of expertise you need later. Documentation users often complain about help systems that provide general instructions (which they know), but don’t provide the answer to their problem.

Best of Both Worlds

The governor considers all of these ideas for some time. He then presents a combined plan to the committee. The combined plan joins the “Not So Many Roads” plan and includes a revised “Minimalism” plan as well. The committee has already determined the busiest cities and the best routes to them, where most of the traffic travels. These routes should be prominent on the map and warrant the most maintenance. Roads to smaller, more remote locations would also be maintained, but because there is less wear and tear from traffic, the expenditure is small. The map for this plan looks something like Figure 6.


Figure 6: Minimalism and Cross Reference

Documentation Advantages

This system can also benefit a documentation plan; a map like this one provides a good way to incorporate existing documents into a new plan. When more technical documents are linked properly to main documents, users can access the information they want quickly.

Documentation Disadvantages

You may require careful planning to decide which the main documents are and which other documents should link to them. This planning requires a careful study of existing documents, which can be time consuming—but the results are worth it. CIDMIconNewsletter


Todd Herrick

Symitar, a JHA Company

Todd has a BS degree in Computer Science and has been a technical writer at Symitar for 11 years and also has technical writing experience there and at other companies for over 30 years as a programmer and data analyst. He spent two summers as a surveyor in Alaska while in college.