December 18, 2014

Can Tech Writers Create Links without Even Writing Them?

This article discusses why links are important, and how technical communicators can make them without actually explicitly writing them.

Some technical communicators say that links should be handled with care, especially in a topic-based environment, since you can end up with broken links depending on how you organize and filter topics. Also often discussed, is whether links should be embedded or inserted at the end of a topic as a list of references. The technical communication community has at least come to the agreement that creating a link strategy, and the actual links, is a time consuming affair.

In this article, number nine in the Designing for the Searching User series, I show how links can be generated from content classification (that is, lists of metadata —taxonomies — used to classify content). But first, I discuss why links are important. Then I shortly introduce you to what it means to classify content and why we should do it.

Why are links important?

To understand why links are important, and why one should put effort into creating them in the first place, we need to first understand how users behave when interacting with user assistance.

When stuck in product use, users ask questions and search for answers. They begin by selecting the most relevant information source, perhaps the user manual  The user then selects and skims a search interface, for example, the table of contents to identify pages that seem relevant to their current question(s).

When a selected page is opened, the user skims the text or image to judge whether it is relevant to the question. If so, the next goal is to understand what the text or image is trying to say by way of deeper reading.

To find a page in a manual or on the internet is not difficult. Just open the manual, or Google. The difficulty lies in judging whether the information is relevant to the question being asked— and, if it is, the challenge becomes understanding the information.

From this perspective, links really are a good way to help users judge the relevance of information, and understand it on a deeper level. How? When users attempt to judge relevance and understand content, they may ask follow-up questions. If encountering a central term like “ABC," which is not understood, relevance cannot be judged. And so, the user asks: "What is ABC?"

Furthermore, a user trying to learn how to perform "function X" by reading a text describing it may find out that it needs to be set up first. Therefore, they ask: "How do I set up function X?" As you can see, links are important since they provide answers to follow-up questions (as discussed in article 5).

Finding the answer to a follow-up question may trigger a chain-reaction of new follow-up questions. A user landing on a page that  fails to provide links to follow-up questions within the context of an answer finds themselves at a dead end. Users become frustrated if they have to “go back home" to begin a new search for answers to their follow-up questions.

Still not convinced? Let's imagine an individual who wants to make meatballs. They find a webpage featuring a recipe for meatballs. The individual judges it to be what he or she was looking for, and has no trouble understanding it. Ok, so what is the purpose of putting a bunch of links onto this webpage then?

Well, you could insert links that lead to other recipes for the purpose of enlightening the page visitor about new cooking possibilities. In this case, the user does not need to follow the links to understand the meatball recipe. Rather, such links act as triggers to new information needs and cannot be defined as a follow-up questions. Information retrieval of this sort, however, denotes serendipity and is not the focus for this article.

To me, links in a traditional user manual provide some of the little explicit evidence within the book-like design paradigm that the technical communicator had the searching user in mind.

What is content classification?


Figure 1_facet taxonomies

Figure 1

Before I discuss how content classification can be used to generate links to follow-up questions, I'll briefly introduce my view of content classification.

Imagine that you have predicted and written a lot of answers to many user questions. There are various types of answers, such as procedural, conceptual, etc. For the sake of simplicity, each of the icons in Figure 1 resemble an answer to a user question.

Imagine that you, as part of predicting the questions, have developed a number of independent metadata lists— taxonomies — based on the characteristics of the answers. Our icons in Figure 1, the example taxonomies, represent Shape, Size, and Color.

Each answer is assigned one value within each taxonomy. Thus, the answer in the upper right hand corner is classified as “Triangle,”“Small,” and “Red”.

One reason to classify answers is to make them easy to find. You can build a faceted navigation portal and display all the taxonomies at once, thus enabling users to select any value in any taxonomy— similar to an e-commerce site. If the user selects “Red” in the color taxonomy, all icons (answers) not categorized as “Red” are automatically filtered out. Article 3 presents this approach in more detail.

How do I generate links from content classification?


Figure2_facet taxonomies

Figure 2

To make the above example relevant for technical communication, consider Figure 2. The Shape taxonomy from in Figure 1 now represents various file formats that a software can output. The  Size taxonomy represents different tasks the user can accomplish with the software.  The Color taxonomy signifies different software interfaces.

The answer (icon) in the upper right corner answers the question “How do I move a RTF file in the operator interface?" and is classified as "RTF", "Move," and "Operator Interface".

The classifications are used to generate links by the applications that render, for example, a web output (like Excosoft exFinder). In such web output, the classification is visible as tags beneath the answer. In our case, clicking on the tag "Operator Interface" opens a popover that lists all answers also classified as "operator interface”.

In our example, answers on how to  create, move, and delete PDF, RTF, and TXT files from the operator interface are listed. Maybe the user was looking for information on how to delete an RTF file, but opened an answer on how to move an RTF file. With the help of the related answers generated via  the classification, the answer on how to delete could be found.

Notice that the answer to the question, “How do I move a RTF file in the operator interface?"includes the term “move." This term is classified as a "move" value in the task taxonomy (See Figure 2). This is because the user might have a follow-up question related to "move".

When a user clicks on the term "move" in the web output, a popover appears, listing all answers that include the classification “move." In our example, all answers for how to move PDF, RTF, and TXT files in operator, administrator, and engineering interfaces are listed.

Note that this approach only works well if the taxonomies are crafted from the perspective of the searching user, which means to understand the type of questions they ask and what follow-up questions they ask.

Ideas on how follow-up answers can be displayed in a web output

Obviously, in both examples above the list of follow-up answers could grow out of proportion if many answers and taxonomies are included in the web output. The solution is to organize answers around the different taxonomies.

When the user clicks on a follow-up answer, they could get distracted if the application opened the link in the same window, causing them to lose sight of the original page. Instead, the follow-up answer could be opened beneath the original answer, much like how comments are visually placed beneath a blog post. Links to external sources, like other web pages, might not work equally well when displayed beneath an answer.

This way, the user can build their own knowledge base by opening answers to follow-up questions. This works well for follow-up answers created within the ecosystem of user assistance. For this to work, answers need to be short, as I have depicted in article 2.

Generating links from content classification addresses many common concerns that technical communicators have on this subject. Using this approach means that you no longer have to worry about broken links in a topic-based authoring environment, nor do you have to create time-consuming relationship tables.

Moreover, showing links in a popover and adding follow-up answers beneath each topic, means that you don’t have to take the fight of deciding whether you should hardcode embedded links or provide a related topics section at the end.

SeSAM is a methodology for designing according to dialogism, or for the searching user. Contact Information Architect Jonatan Lundin at jonatan.lundin@excosoft.comto learn more.

Explore previous editions of the Designing for the Searching User article series via the links below, and stay tuned for upcoming ones!

Previous series editions: Part 1/ Part 2/ Part 3/ Part 4/Part 5/Part 6/Part 7/Part 8

About the author

Jonatan Lundin

Jonatan is a pioneering information architect backed by over 20 years dedicated to XML documentation, and designing for findability.

Post Comment


  • Excosoft
  • Information Design
  • Info Tech Trends

Latest posts

Looking Back on 2016

December 29, 2016

Skribenta 5 Now Released

December 12, 2016

What is a Topic?

November 4, 2015

More from Blog & News