The Spaghetti Code of User Assistance
by Doug Williams
Inline links are very commonly found in documentation. But are they the best answer for customers, and for us?
Every manually-coded inline link comes at a cost, in the form of a single point of failure for builds, and in the form of a barrier to topic reuse. But there are benefits, right? Actually, customers don’t use inline links nearly as often as technical writers think; they have been trained by experience to fear them. Following links from one document to another is essentially using a subroutine buried in a subroutine buried in a subroutine, which, in a polite mood, a developer might call “spaghetti code” or “a bag of ropes.” Users might have other less polite terms, such as “death spiral,” or “*&^%*&%*!” Is your link providing high-value information scent, or does it simply enable you to keep track of table numbers by putting in a link, or save you the trouble of thinking carefully about content you can just link to and forget about?
What Salesforce Found
Salesforce undertook a study of inline link cost/benefits a few years ago. Here is what they found, as reported by Mysti Berry, who was at the time a lead architect at SalesForce.Com:
Herding Tigers: Letting Go of Inline Links
Goal: Every Page Serves a Customer Need.
The following is from Mark Baker’s book, Every Page is Page One. Mark Baker does like inline links–and they do have value for some purposes. But even Mr. Baker notes the following:
Being self-contained can actually make a topic slightly (or even substantially) longer than if was designed to be read in conjunction with other topics. On the other hand, if the reader has to read other topics in order to understand this one, then their reading experience is long, even if the individual topic is short. The brevity of the reader’s reading experience is what matters, not the shortness of the individual unit of content. Making sure a topic is truly self-contained, that it can function independently, contributes to the brevity of the reading experience even if it bumps up the word count.
Fitt’s Law and Links
Fitts Law is the name of an empirically testable algorithm that shows that the time required to rapidly move to a target area is a function of the ratio between the distance to the target and the width of the target. When you fragment a user goal in the form of links, you create a three-dimensional barrier between a user and a user’s goal. If you intend for a customer to read your topic completely, and the links include information that is not immediately relevant to a task, then you have distracted the reader from their actual goal in reading your topic; those links can be put at the bottom of your topic. If you require a customer to follow a link to complete a task, then why is that task not included in your topic? If you want to link to the next topic in a task, then is that link better than placing both topics under a common orientation topic, so that they are organically linked through the standard DITA parent-child-peer linking?
At best, even when links are valuable to users, they increase the cognitive load on users as they try to carry out tasks. There is empirical evidence for this.
The Web Shatters Focus, Rewires Brains by Nicholas Carr
Fitt’s Law also applies to how you link: The more visible a link, the better. A CSS should make links visible. Links in one location – a relatedlinks element, or relationship table, which places content at the end of a topic – makes relevant links easy to find, and encourages readers to at least make it to the end of your topic before leaving. Usually, that’s a good idea.