inline links (Re: Online help access question)
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", http://www.slideshare.net/MystiBerry/herding-tigers.
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".
-Monique
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
References:
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
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads