TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
That might work in some circumstances, but there are a couple of problems with it.
First, the longer a document becomes, the less often it is read. The longer document increases the chances the reader will abandon the document or abandon the task. A document should be as long as it needs to get the job done for the typical user, but not longer. Putting in stuff for the atypical user increases its length for all users.
Second, there is a limit to how far you can take this strategy. If there are only a few things to inline, you can get away with it. If there are many, you will blow up the document beyond all reason.
Third, the relationships described by links are not as simple as the ones that can be resolved by including material inline. This comes back to document thinking again, rather than information set thinking. Links allow readers to move through an information set in a way that could never be generalized by a static sequencing of elements.
Of course, some information is much more bounded than others. Robertâs examples highlight how unbounded information can be for some products. Other information can be much more bounded. But at the same time one of the effects of the Curse of Knowledge (to which we are all subject to one extent or another) is that it makes us think the information we are recording is much more bounded than it really is. Links are not just for the cases we have thought of, but for the cases we have not thought of.
Certainly some documents are legitimately highly bounded. (A pilotâs pre-flight checklist springs to mind.) But for the most part such what ensures that they are tightly bound is not the subject matter but what we can know with assurance about the reader. (The pilotâs checklist is written for a trained pilot who has qualified on the aircraft in question. The subject matter is not bounded; the reader is.)
Mark, the issue you bring up is one of the ways in which electronic materials can be less useful than paper ones. It's also an issue related to using topic-related organization and perhaps CMS systems altogether.
The issue is to make sure that any statements or terms are clear and identified in the relevant area. One can make things "briefer" in appearance by using links to other sections, definitions, etc., but that's a weak way to help ensure that the reader has the correct information. If it's important, it should be spelled out right there. But if the definition or whatever is in a separate topic, it might not be seen as important or relevant. All of this depends on how important that information is. Personally, I might forgo the use of links in many situations and fall back the old (see section XX for more background). But not if the information is important, though I might use it as a reminder inline instead of a link.
Kathleen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
