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

Subject: RE: inline links (Re: Online help access question)
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 5 Oct 2016 11:23:21 +0000 (UTC)

Mark responds as follows:


"If a topic is logically consistent without the benefit of inline links, then you probably shouldn't use inline links."Â


"Obviously, it's commonly good to link to the procedure, but you should do it as a critical choice, not as a rote response. There are procedures, and procedures. And there are different levels of coverage for procedures. Exactly where you link, or whether you link, always has dependencies."

One of the features of document thinking is that it approaches document design on the assumption that the reader is holding the right document. That is, it assumes that finding and reading are distinct activities and that finding has be successfully completed before reading begins. On this logic, the only role of links is within the design goals of the current document.=================
I'd say document thinking assumes the reader is holding the document the reader wants. 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). It assumes the reader got to the topic via some directed pursuit, and there is some logical way to satisfy that pursuit.

DITA certainly supports this topic/document relationship. It begs the question, can there ever be a "right" collection of topics for a given query? 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... I'm sure there are other things you can do (like Jang Graat's link-as-search-query).
BTW, if you look you'll see that including static links in a topic is just another way to assert a "right collection" of topics -- no more virtuous than authoring a static collection of topics. It's probably the easiest way to do it -- you don't have to express any relationships between the topics except that you think a link belongs HERE. Compare that to automatically generating links... In that case you need to encode relationships so the machine can know when to generate a link. That's more work. (Assuming you get it right, then you are lifting some effort off of the shoulders of the reader... Usually a good thing to do.) It's not necessarily more virtuous than static authoring, because it still relies on your choice of encoding/process. But it does open up more ways to express the relationships you have encoded.

I see nothing in topic-think, nor in DITA, that keeps you from doing all these things. In fact, I already do 1 - 4 in my docs, and I do a very cheap version of 5 (related links based on the assembled hierarchy). Just because DITA can support document-think, that in no way means it limits you to document-think. But support of documents is good -- there are still people who ask for a PDF -- and I can generate multiple "documents" from the same source I use to generate dynamic content widgets in the product GUI. In fact, I'll claim that we're blurring the distinction between product and "document" -- Now there's a subject that should stir up a hornet's nest.

Also, just because you generate and present an ordered collection of topics, that in no way keeps you from expressing these other hypertext constructs, nor does it keep the reader from using them. All you're saying is that you or your system guesses that this ordered collection is of value. Is that document-think? Or is it just trying to do some heavy lifting for the reader?

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 @


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