Why Your Content Needs More Links

Technical Communications needs to make far greater use of linking than it does today. Here’s why.

In a blog post WordPress for Beginners: Too Many Choices? Sufyan bin Uzayr quotes an email from novelist Meg Justus about her frustrations trying to get started with WordPress:

The reason I’m finding self-hosted WordPress so complicated is that it asks me to find a theme first, before I even know what I’m looking for. All the “how to choose a theme” websites I find assume I know far more about what I want out of a theme than I do. Most of the language used to describe themes isn’t language I understand (WordPress’s own “search for a theme” is horrible in this respect – how am I supposed to limit down by function if I don’t understand what the words describing those functions mean?)

This is a classic user problem. They are not setting out to learn the product. A 20th century response to Justus’ problem might have been to suggest that she read a good book on WordPress so she would understand all this stuff before she started to do anything, but that is not how things work today. People’s expectations of user experience have galloped far ahead of our ability to deliver. People expect to be able to just do stuff.

This means that Justus expects to just be able to set WordPress up the way she wants it to work. She skips learning WordPress and jumps straight into trying to make it work. Inevitably, she runs into a bunch of terms and concepts that she does not understand.

How could the documentation she is reading be improved to make her experience less painful?

  • It could explain everything from scratch. Except, she is looking at websites from many different theme suppliers. They are not all going to have the resources to explain everything from scratch. Nor would it make sense for their business model, since most of their real revenue probably comes from professional site developers who already know this terminology. And, in any case, this would amount to making every site be the textbook on WordPress which Justus could have found and read if she had chosen to. So even if they did explain it this way, chances are Justus would have rejected this in favor of something shorter.
  • It could have left out all the confusing terminology and extra options. Except, those options actually matter. They are all there for a reason, and while any one reader might not need all of them, you don’t write for one reader, you write for all of them.
  • It could have provided links from all the confusing terms to topics that explained them. The authors would not have to write all those topics themselves. Most of them are common concepts that apply across the WordPress community. Authors could simply link to the best available topic on that subject.

Links, therefore, help the reader to fill in the blanks in their background knowledge so that they can understand the content and get their work done.

Now, you may be thinking, wouldn’t it be better if WordPress were made easier for beginners to use? That is indeed what bin Uzayr is arguing for in his piece. But in the real world, this does not happen very often, because there is usually more money to be made in adding features. Not to mention that simplifying things can often break backward compatibility for existing users, and fixing those problems can be truly complex.

While there are breathtaking examples of the new and simple blowing way the entrenched and complex, that is not the normal way of things. In fact, I would suggest that there is a clear pattern in the history of many products that shows that novices do not start using a product in large numbers until it has become too complex for novices to grasp.

Why is this? The problem for novices is always, how to choose? The fear of making the wrong choice is very strong, so novices will generally flock to the market leading products. Word Press is the market leader in the Web CMS world, so the fear of making the wrong choice is allayed. (How to you think I chose WordPress as a platform for this blog?)

The attractive thing about the market leader is that it has a lot of users and a lot of companies providing support and services and add in products. It is going to be easy to find someone to help if you need help. And because it is a market leader, it is probably not going to disappear over night (this is not nearly so assured as it used to be, but big is still more stable than small). If you choose big, your choice is less likely to become an orphan.

The problem with the market leader is, its product has been around for a while. As it has grown up, people have asked for more and more features. Those features have been added, but, because the original architecture was not designed for them, they may have been added in less than elegant ways. There may be overlap between features, and between built-in features and those provided by third parties. There are therefore a lot of choices you have to make, and a lot of stuff you need to know to make those choices wisely.

And even if you did make one, the simple version would have fewer features and fewer options, and most users are going to want something that is not in the reduced feature set. If not today, they are going to want it tomorrow.

However much users may say they want simplicity, it is very hard to convince them to give up functionality for simplicity. (How many writers shopping for tools ask, can this tool make PDFs that look just like our current template?) To each user, the thing they want may appear pretty simple, but every user wants something slightly different. Complexity is the sum of a thousand simplicities.

Justus asks for just this kind of simplicity,

I just want to be able to tell it that I want this photo as my header, to have mostly static pages plus the blog, to choose my fonts and my colors, and to mirror the blog posts to my other social media sites.

There are probably a hundred small simple Web CMS products that would do these things without all the complexity that WordPress presents. Why didn’t Justus choose one of those instead? She does not say, but probably because none of these systems have the characteristics that make them seem like a safe choice for a novice. They are small, they have few users and few supporters. There’s no one to help. I might not be able to get my content out if they close down or don’t keep up with the features all the cool kids will be using next year.

Making a good choice among many obscure products is very challenging — a problem that Justus ironically runs into within the WordPress ecosystem when she goes looking for themes. The first adopters of highly simple products are often the geeks who are capable of assessing their merits and confident in their ability to support themselves.

Novices, therefore, flock to products at just the point that they have become too complex for novices to use. (Tech Writers are flocking to DITA these days, just as the chorus of criticism is rising about how complex DITA has become. A simplified version of DITA is being created in response. This is not a contradiction. It is the way tech works.)

All this is good news for tech writers, of course. It keeps up the demand for technical assistance in all its forms. But it is also why technical communications needs to make far more use of links. Because people are diving into complex products without making a systematic study of them first, and with and expectation that, as market leaders, they should be simple.

People are diving into the middle, and finding more questions than answers. They need a way to get a quick shot of information on the difficult terms they encounter. The best thing we can do for them is to throw them a link.

, , ,

20 Responses to Why Your Content Needs More Links

  1. Chris Despopoulos 2014/01/20 at 17:38 #

    If the fulcrum of this piece is the statement, “Authors could simply link to the best available topic on that subject”, then yes, yes, yes. In fact, this is what Ted Nelson was going on about back before HTML became the ubiquitous thing it is today. He had a scheme for authors to use links as citations of other authors’ work so that the link could be followed as the reader chose, and the author could get paid for every access to his content.

    Well, things didn’t shake out exactly that way, but linking is what it’s all about. I think Mr. Nelson believed authors wouldn’t contribute text without getting paid. Thanks to the internet, we know that was wrong. Also thanks to the internet, we know that a million monkeys typing on a million typewriters will NOT produce the works of Shakespeare. (Not my joke…)

    There’s no reason not to have links to broader or deeper discussions about a point — super parentheses, mega end notes, or just expanding sections and paragraphs. And for product documentation, there’s no reason to wait for a document page to present an entry point into this trail. The GUI can have text in it, and that text can have links. And off you go.

    • Mark Baker 2014/01/20 at 21:18 #

      Thanks for the comment, Chris.

      Agreed absolutely that links can and should start in the product. There is no reason (other then integration issues) why the user should be presented with a dialog box with a bunch of strings containing words they don’t know, and have to click on a help button to get to a page that may or may not explain those terms, or may link to explanations of them. There links should occur in the dialog box itself.

      Of course, it is the integration issues that get in the way of this. This is why we need soft linking, so that the creator of content does not have to go looking for content to link to, which, in the case of the dialog box may not exist yet. We need a system in which link targets are discovered at run time based on metadata.

      Interesting stuff about Ted Nelson’s vision. I wonder if there is something of a pattern here. It does seem that our ability to understand the economics of new technology trails our ability to see its physical applications.

      • Chris Despopoulos 2014/01/21 at 07:41 #

        Yes, discovered targets and some semantics to sort out which links should go where… Definitely the way to go. For me, within the confines of product documentation, the first step is to make sure the docs are distributed with each product “service”, and the actual topic set to display can be discovered on the fly. Certainly, when that’s under control, I want to move away from explicit links and over to generating links out of the currently discovered topic set. Or rather, MUST move over there…

        All of this is all the more possible when talking about web apps, where the GUI is itself a web page (a “document”). In software we’re learning that products themselves are essentially engines to display and modify data… How is that different from “document” authoring? So why should there be a clear separation between product and documentation?

        • Mark Baker 2014/01/21 at 11:19 #

          I think in many cases that the historical organization of companies influences design in this respect. Documentation is separate from product because the documentation department is separate from the engineering department. We need to recognize the sometimes there is a design bias built into the org chart.

          (On that score, why are tech support and tech pubs two separate organizations? They both do exactly the same thing.)

  2. Marcia Riefer Johnston 2014/01/20 at 17:45 #

    In cases where many pages are related in many ways for readers at many levels of expertise—and where those readers have a dizzying array of possible questions they want answers to right there—how do you decide how many links are too many to toss for fear of drowning them?

    • Chris Despopoulos 2014/01/20 at 18:57 #

      I tend to think that good writing knows how to set this kind of bounds on a paragraph. You just don’t stuff too many ideas into a single paragraph if you want your text to be readable. So how many links could you need in a paragraph?

      Well, if it’s a matter of terminology, then maybe one link to a glossary could minimize the mess. Or post a listing of the terms apart from the paragraph itself. Of put tooltips on the terms. Suddenly the answer to your question is affected by the technology you have available. That’s why what we do is at least a craft, if not an art.

      In my comment above, I mentioned Ted Nelson. On a lark, I checked out what he’s up to these days. If you want to see something wild in terms of dizzyness and drowning, check out Project Xanadu… He’s flying through a space of “pages” that can merge together citations (transclusions) from any medium using FLinks (flying links) to make source content Sworph (swoop and morph) into view.

      Check it out — if you give it a chance it’s really pretty interesting… http://www.youtube.com/watch?v=En_2T7KH6RA

      • Mark Baker 2014/01/20 at 21:51 #

        “Paper is a prison.” Indeed. It is interesting how Nelson’s ideas parallel those of David Weinberger in Too Big to Know, where he talks about how the technology of paper and boxed and flattened our view of what knowledge is.

        Where I part company from Nelson, and many other who have done similar things, is where they put the emphasis on visualizing the overall structure created by all the links. I don’t think this is helpful at all. Visualizing the structured of a complete set of links ends up just looking like spaghetti. The point is not to visualize links, but the follow them.

        Again, the point is to learn the subject matter, not to learn how the texts are connected. The texts are just one tool we use to reach an understanding of a subject. Links let us navigate texts along lines of subject affinity, but it is the subjects we ultimately care about, not the relationships between texts.

        • Chris Despopoulos 2014/01/21 at 06:51 #

          Yes, there is something terribly academic in what we’re allowed to see of the Xanadu project. I think he’s grappling with attempts to break out of the paper metaphor, and using the technology to visualize a possible exit. But even his displays of content units are on vertical planes (sheets of paper). Even Xanadu seems to be in the paper prison.

          There’s another approach to that. Limits can be a source of creativity. Haiku is haiku because of its limits. The blues are infinite in variety, based on some few simple chord progressions. Et cetera… The limits of paper can be maddening, but how much of our current technology has its roots in symbols on paper? I tend to think all of it, excepting very primitive technologies that owe only their remarkably extensive refinement to paper (baseball bats come to mind). I think a Xanadu problem is precisely in that… You can’t throw away so fundamental a paradigm without offering a workable replacement.

          But I definitely agree… Visualizing the underlying structure is a fool’s errand. The better goal is to visualize the conceptual structure.

          • Chris Despopoulos 2014/01/21 at 07:47 #

            BTW, another goofy web page to look at for visualizations of underlying structure…
            http://www.bbc.co.uk/news/uk-england-tyne-25137759

          • Mark Baker 2014/01/21 at 11:27 #

            Actually, I think the prison of paper is not the linearity of text. Text is linear because language is linear. Complex relationships may get constructed in the brain, but, like complex data structures in a computer program, they have to be serialized for storage and exchange because we (people and computers both) have linear I/O mechanisms.

            What makes paper a prison is the high impedance between one piece of paper and another. A person moving from one text to another is still behaving linearly. They are just following their own line, driven by their own interests, not the line drawn by the author.

            The Web does not change the linear nature of individual texts. It simply removes the impedance between texts. It does this in several ways, such as search and social curation. Authors should actually be embracing links as they are the only form of connection between texts that is in the author’s control.

          • Mark Baker 2014/01/21 at 11:33 #

            Re that page from the BBC — great find by the way — I think it really reinforces the point I make in the book about the Web being organized bottom up. Look at any well designed page and all the links make perfect sense. Look at a map of all the connections, and it is just a meaningless mess. The Web makes no sense top down. Individual Web pages make perfect sense bottom up.

            The thing is, top down models inevitably break down beyond a certain size, becoming unnavigable Frankenbooks. At Web scale, bottom up is the only arrangement that works.

    • Mark Baker 2014/01/20 at 21:37 #

      Thanks for the comment Marcia.

      Let me turn the metaphor around. The reader is drowning first in their own problem and the need to understand all the real world factors that affect what they are trying to do. Secondly, they are drowning in the material they are reading and all the unfamiliar concepts they are struggling to relate to their problem. At that point, how do you decide how few life preservers you should throw to them?

      Look at it this way, and you can’t throw them too many links.

      Of course, you should make sure that you are throwing them good links. It needs to be clear what you are linking to, and the thing you are linking to needs to be good content on the promised subject that is genuinely helpful. The problem with links, often, is that they are created so carelessly or haphazardly that they are like a lifesaver made of stone, or a bunch of flotsam thrown on the water that just make it harder to find the real life preservers.

      Multiplying links is useless unless we also improve their quality. I don’t know how many organization have a systematic and disciplined approach to linking, but experience suggest that it is not many.

      Chris also makes an excellent point. Links reflect subject affinities. If the text is referring to too many subjects too quickly, that may result in too many links on divergent subject, but the fault then is in the composition of the text, rather than in the links.

      There are, of course, some writers who dislike linking because they feel that they will distract the reader from the text. This can arise from a schoolroom attitude to the reader and the text: that it is the reader’s job to comprehend the text. But this is not why anyone reads anything unless they are going to be tested on it. People read to understand subjects, not texts, and, more often than not, understanding a subject requires a particular combination of texts, fragments of texts, conversations, and experiences that is unique to each individual. Links help people make that journey.

  3. Suyog ketkar 2014/01/21 at 00:40 #

    Mark, the article is undoubtedly one of the best articles I have read from you.
    It is correct to say that today’s articles need more links when compared to those written previously. It also is agreeable that novice readers tend to shift towards popular, bigger, and more complex tools.

    I recall having read a similar behavioral pattern in Freakonomics, a book coauthored by Steven Levitt and Stephen Dubner. In the book, the authors show this pattern by matching the economics with that of the naming pattern for children. A common thread between the book and what you’ve written (besides the choice of the bigger, better, and more complex tools/names) is that it tells you a lot about yourself. If I, as a tech writer, can judge the behavior of my readers, I can write better, more effective content for them. After all, my purpose is to get read and understood correctly.
    Readers read based on what they think. If they are looking for a solution, they will read only the topic that contains the solution. If they are seeking information, they will read two more topics, but again, they will read only what they think matches their search. I must, therefore, prepare my documents that are topic-based and crisp. And, that’s exactly why Justus was unable to find what she was looking for. Either the books are bulky or the content is spread across the book, and hence, difficult to comprehend. And, as a tech writer, that is not I would want my content to do for the reader.

    Also, how much linking will the reader appreciate is a question that demands probe! I would not want to clutter my content so much that it loses its value. But, I wouldn’t even want my reader to be clueless even after reading the content thoroughly.

    Thank you, for the article.

    • Mark Baker 2014/01/21 at 11:51 #

      Thanks for the comment, Suyog.

      Actually, I don’t think that Justus problems arose from problems in the text, but in how she chose to use the text. WordPress genuinely is more complicated than Justus wanted it to be. That is not the fault of the documentation.

      Actually, I think it is the fault of the marketplace and how it works. The reason Justus chose WordPress (I think it is fair to presume) was not because it is the simplest choice but because it is the most popular choice. And the reason it is the most popular choice is that it has been around for a long time, has been adapted and used for a wide variety of purposes, and has attracted many add on products. All of these things make it more complicated, and force the new user to make many decisions that they are not equipped to make.

      We can see this drama played out on a large canvas in the battle between Apple and Android. Apple, tries very hard to hang onto simplicity through tight, almost draconian control of the platform and what can be added to it, while Android throws the gates open to all comers to add features (and thus complexity and choices) to the Android world. But doing what Apple is doing is very difficult. Most products don’t get to a market leading position with their simplicity intact.

      In short, the market drives complexity into products, while users don’t take the time to learn about the product first, but jump into the middle trying to do things. This is what creates the need for links in documentation, to help people who have jumped into a complex product as the deep end to find a way to swim.

  4. Scot Marvin 2014/01/22 at 15:39 #

    Dammit, Baker, quit writing stuff that makes me think. My brain is hurting.

    (Thanks for the headache though.)

    • Mark Baker 2014/01/22 at 17:20 #

      Thanks for the comment Scott.

      Alas, you are not the first person to accuse me of giving them a headache. 🙂

  5. Jennifer Bulman 2014/02/07 at 22:06 #

    Mark,
    Reading this post, and others, makes me feel like I just found a sane person hiding in a universe of insane ones. Thanks for the clarity in explaining the user dilemna.

  6. Anna Addington 2014/02/20 at 13:45 #

    I agree that our current culture demands easy access to additional content, but broken links can be a frustrating experience for end users. How do we balance the two?

    • Mark Baker 2014/02/22 at 02:19 #

      Thanks for the comment, Anna.

      What we do is manage our links so that they don’t get broken. For links within our own material we can do that reliably with the right approach, such as the one I outline here: http://everypageispageone.com/2011/08/01/more-links-less-time/.

      For links to external material, we need to have a regular process of review that makes sure links stay intact. This can be largely automated, though some human oversight is likely necessary as well.

      These measures are not prohibitively expensive or difficult for organizations that recognize the importance of links. Broken links are generally a sign of organizations that don’t build link management into their process.

Trackbacks/Pingbacks

  1. Passive vs. imperative linking | Every Page is Page One - 2014/04/16

    […] am going to recommend you read a couple of other articles that I have written on linking, such as Why Your Content Needs More Links and The Nature of Hypertext. These are imperative links. I am referring to specific articles and […]