inline links (Re: Online help access question)

Subject: inline links (Re: Online help access question)
From: "Monique Semp" <monique -dot- semp -at- earthlink -dot- net>
To: "TechWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 29 Sep 2016 14:08:12 -0700

This second point should be elementary for all product documentation in the hypertext age. You should never, ever, mention a system function or procedure without linking to that procedure.

I whole-heartedly agree, and yet there are many admonishments for people writing in DITA to eschew links in the content. So I now include links only sparingly, but I do still include them. I just try to decide that there's a real potential benefit instead of just automatically linking to somewhat related info.

(And yes, here meant to say "DITA", not "structured authoring", because although this point is relevant to *any* writingâboth structured and "unstructured", I've encountered anti-link vehemence only when reading/hearing about DITA-specific authoring or when being edited while working in a DITA ecosystem. But of course, the argument about including links is relevant regardless of authoring/publishing system.)

There's a slideshare from 2013 that really made the rounds a few years ago in the San Francisco writing community, "Herding Tigers: Letting Go of Inline Links",

It was timely because I'd been working in DITA in an organization that (gasp!) had a great editing team, which was when I was first "subjected" to the "no link" rule. That was the style, and so of course I had to acquiesce. But separate from that, I had a great written exchange with this slideshare's author.

The major points, pro (include links) and con (exclude them), boiled down to:

Con (exclude links):
* It's a crutch that soothes the writer and wastes time (especially to maintain the links).
* Statistics show that users tend not to return to a page after they link away.
* Statistics show that most links simply aren't clicked.

Pro (include links):
* Supertasks (a task where each step is itself a complex task) benefit from links; otherwise users have to search.
* Doc reviewers *always* want links. (No, doc reviewers don't always know best. But especially if you're a consultant, you must keep the team relatively happy.)
* They "just feel right".


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 @

Online help access question: From: Suzette Leeming
Re: Online help access question: From: John G
RE: Online help access question: From: Robart, Kay
RE: Online help access question: From: mbaker

Previous by Author: Re: Job email rules and moderation prison
Next by Author: Re: Documentation for REST APIs
Previous by Thread: RE: Online help access question
Next by Thread: Re: Online help access question

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

Sponsored Ads