RE: inline links (Re: Online help access question)

Subject: RE: inline links (Re: Online help access question)
From: <mbaker -at- analecta -dot- com>
To: "'Chris Despopoulos'" <despopoulos_chriss -at- yahoo -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 5 Oct 2016 10:41:47 -0400

"I'd say document thinking assumes the reader is holding the document the reader wants."

Yes, that is what it assumes, and it is often wrong. In tech comm, users don't want documents at all, they want answers. And figuring out which document contains the answer they want is often difficult. The reader starts with a business problem. Is the feature that solves that problem as standard part of the product? If so, they want the user's guide. Is it something that needs to be turned on by the administrator? If so, they need the administrators guide. Is it something that needs to be added by calling the API? If so, they need the programmers guide. But since they don't know which of these it is, they don't know which book they need. If the book they pick up is written on the assumptions that the reader has the book they want it is not going to help them get to the book they really want.

And this is, of course, is why people prefer to search: because it does not require them to guess which book they should be looking at. And it is why we should link, because if search gets them close, links can take them the rest of the way. This is why hypertext thinking matters.

"But topic-think does not equal document-think. Topic-think says there is a unit of text that should be self-consistent and complete, and that unit is less than a document. One document can be made of many topics, and one topic can be included in many documents. But also, one topic can stand on its own (in theory, anyway). "

There is a good reason that I contrast document-think with hypertext-think not topic-think, and this illustrates it well. I would suggest that there are three forms of topic think:

1. Topics are building blocks of documents. From a design point of view, this is document think, but the document think applies to the document, not the topic. Topics in this case are orthogonal to the question.

2. Topics are stand-alone entities that satisfy a single user need. This is document think with document writ small. Topics are designed as if they were brief documents: as if the reader has the correct topic, that the topic satisfies the need, and that the whole topic is required to satisfy the need.

3. Topics are nodes in a hypertext network. This is what I call Every Page is Page One. This is hypertext think, by which I mean that each topic is designed to function as a hypertext node, that it has both navigational properties and informational properties.

The great DITA fallacy is that 1 and 2 are the same thing. They are not. The increased emphasis on chunking that the committee has announced as a priority for the next version suggests that this fallacy is increasingly being acknowledged.

"It assumes the reader got to the topic via some directed pursuit, and there is some logical way to satisfy that pursuit."

This is the defining characteristic of the second definition of topic. It essentially treats navigation as a separate pursuit outside the scope of topic design. It assumes that the quest for the correct document has been successfully completed before the reader opens the document. Topics are not nodes in a network but leaves on a tree. Document design therefore takes no account of the possibility that the reader may not have the correct document.

The basic fallacy of this view is that it assumes that the reader is in possession of all the information required to select the correct document (which would be necessary in order to direct their pursuit). But this is clearly false in many case (as the example above illustrates). You often need information that can only be hand from the documentation in order to know what information you need from the documentation, which makes finding and reading an iterative operation, not a linear one.

"[C]an there ever be a "right" collection of topics for a given query?"

Ever? Sure. But the questions that matter are, can there be a right collection of topics always or even typically? I would suggest that the answer is no, for two reasons: the author/publishing system does not have enough information about the reader and cannot economically or without violation of their privacy get that information, and the reader often does not know what they are looking for. The information seeking process is iterative and cannot be rolled into a single query that creates the entire information path.

" I think the answer is yes, and there are different ways to put that collection together... Off the top of my head:

1) Author a static collection of topics, asserting your "authority" to choose the right collection
2) Author a single topic with static links to all other topics that might be interesting
3) Encode your source in a way that you can dynamically assemble the "right" collection of topics based on the query
4) Encode your source in a way that it can include dynamically generated content
5) Encode your content so that you can dynamically generate links based on the query
6) Encode your content so that it can respond to an increasingly refined query"

To take each of those in turn:

1) This is classic document think. The objections to it have already been stated.
2) This is hypertext think.
3) This is document think. It assumes you can assemble the right document for an individual, with exactly the same assumptions as classic document think. The objects are those stated above.
4) ditto
5) ditto
6) Progressive refinement is sort of a hybrid between document think and hypertext think. The reader's traversal of a hypertext represents the increasing refinement of the readers understanding of a problem, but it does not create an artefact. Progressive refinement builds a document as a result of the reader's traversal of the information space.

The question then is, is there an advantage to progressive refinement compared to hypertext. In most cases the answer is no, for two reasons:

1. By the time the reader has completed their traversal of the information space, they have the information they need. Assembling a document that reflects that traversal is now pointless: the reader already has the information they need. (And saving the document for others is probably not of any value either because a reader only knows that that is the document they need after the traversal is complete. All you will do is create a huge store of slightly variant documents that confuse searches. )

2. Whatever the refinement mechanism is, it will be more complex and less familiar to the reader than search and clicking links. The reason that people tend to default to search as an information seeking behavior is not that it is fast or efficient, but that it has a minimal cognitive overhead. People have limited cognitive resources and when they are struggling to solve a problem, those resources are stretched to the limit. Figuring out fancy progressive refinement systems requires diverting cognitive resources from the problem at hand to the system. All the studies show that most users skip all that and go straight for the search button. (Additionally, information foraging theory suggest that search may in fact be the most efficient strategy even though people are usually bad at it. The reason being that they don't have the information they would need to use other methods effectively.)

Progressive refinement systems are great for some things though. If you need to refine a set based on multiple criteria (all of which you understand up front) then progressive refinement is absolutely the way to go. My go-to example is used car sites like Autotrader that let you find a used car that meets your specific set of requirements. A flat hypertext would suck royally for this kind of information finding. But this kind information seeking is relatively rare in tech comm.

Documents thinking makes us feel like we are not doing enough for the reader when we give them a plain old hypertext. The problem is that all of our attempts to make documents that better fit their needs falter over the basic problems that neither we nor they understand their needs well enough to make it work, and the mechanism of document construction all have more cognitive overload attached than plain only hypertext.

Finding information is a messy business. Hypertext thinking is a surrender to the inherent messiness of the process. It seeks to make the traversal easier through consistency of the nodes and effective linking, but it stops short of trying to fashion the perfect experience. Document thinking wants to clean up the mess entirely. It is a laudable goal, but futile. And the real problem with it is that in practice it usually produces an information seeking experience that is messier than it would have been with a well-designed hypertext.

There are specific situations in which both static and dynamic document-think approaches can produce results that are superior to hypertext. But we need to start treating hypertext as the default and get better at recognizing the exceptional situations where the document approach actually works better.

As tech writers, one of our mantas is to know your audience. Where we often fail to follow this mantra in in the area of information finding. We have to ask ourselves, what type of information finding is my audience willing, able, and sufficiently informed to do. In the majority of cases, the answer to that question is search and click links. (This is well supported by multiple studies.) We should be designing our content to support the information seeking behaviors our readers are most likely to use. There are certainly cases where the answer is not search and click links, and we need to recognize those where they occur. But if we are going to practice user-centric information design, the starting point for that is to support their typical information seeking behavior, and the default way to do that is to create hypertext.


Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


RE: inline links (Re: Online help access question): From: Chris Despopoulos

Previous by Author: RE: inline links (Re: Online help access question)
Next by Author: RE: inline links (Re: Online help access question)
Previous by Thread: RE: inline links (Re: Online help access question)
Next by Thread: Re: inline links (Re: Online help access question)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads