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.
Random deep thoughts (by Jack Handey)...
I have a problem with the following statement:
"Thinking about the embedded steps though, I've worked on materials where
people should not be led astray. So I'd suggest these are especially
situations where links should not be used."
We're forgetting the logic of what we're writing. If a topic is logically consistent without the benefit of inline links, then you probably shouldn't use inline links. If the topic needs inline links to maintain its purpose and consistency, then you probably should use inline links. As professionals it falls on us to figure this out, but the basis should be the logic of the topic.
I also have a problem with this:
"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."
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.
About this statement:
"I became tired of pointing out that theÂ
human effort "saved" in automatic indexing was destined to be expendedÂ
many times over by the people who were trying to use the documentation."
Conservation of energy... Converting data to information is work -- it requires an expenditure of energy. Either the writer does that work or the reader does. Ultimately, the reader always has to do some work. The question is, how effectively has the writer mitigated that via his/her work? And with online docs, you can do the work of encoding data into the document, and let the computer do organization/presentation work for you (electricity, mechanical advantage, etc.). You can even encode calls to get data, so you don't have to look it up yourself (and maintain it as it changes). This is why the up-front effort of encoding (read DITA) is worthwhile for some publications.
Take this, for example:
"I'm wondering how then you would account for different levels of users.
Beginners will likely need more information and as they get more
comfortable, less and less."
Encoding gives you lots of alternatives, letting the computer do the work. You can generate links, you can filter content per user role, you can generate unique content... There's lots to exploit, if we can only get the funding and time to exploit it!
About this:
"With hundreds or thousands of commands, components, APIs,
configuration settings, third-party integrations, reporting options,
etc., the number of possible different tasks customers might perform
approaches infinity."
and this:
"Sure, Robert. Do each of these situations involve finite steps? If so, how
does anyone figure out how to work anything."
The point of a GUI is that it's like a language, with nouns, verbs, and modifiers (adjectives, adverbs). The point of a language is that you can produce an open-ended set of unique statements. Each statement involves finite "words", just as any procedure involves finite steps. But you would no sooner try to list all the possible statements in a language than you would list all the possible procedures in a rich GUI. The problem of learning a product is more like language acquisition than it is like learning a specific narrative. Our job is to give people enough so that they can buy a train ticket (or otherwise navigate in the foreign country), get along with the locals, and take the leap into an immersive experience if that's appropriate. Different user roles yield different levels of documentation.Â
Finally, about inline links...
Yes, you can put traditional links/xrefs into DITA if you want. I certainly do, but in my case the document domain is pretty well bounded. I do generate PDFs that are subsets of the online version. How do I convert dangling xrefs into PDF? I find them and replace the xref with a string similar to "the Product Documentation". So then the inline link says, "For more information, see the Product Documentation." Clunky, but technically correct.
Jan Graat demonstrated another approach... You effectively encode a search in the xref, and let the system search the current domain for possible links. Hover on the xref to get a list of hits. This still has a problem in PDF, but you could run the search at generation time, and if no hits resolve in the subset then fall back to a default string.
DITA suggests you encode the set of links in a map. These are links to topics, not to specific elements within a topic. (Eliot Kimber has worked out some baroque way to get over that limitation, but I leave that to more hardy souls than I.) Note that the DITA OT knows how to look at the map and generate a list of related links at the end of the topic. I believe that's in the DITA OT (one possible implementation of DITA), and not in the DITA spec itself. There's nothing to keep you from implementing your own way to use that map inline, and fall back to a default response if no links apply.Â
Anyway, I obviously see benefit to using inline links. I think they serve the reader, and it's our job to serve the reader in whatever way possible.Â
cud
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
