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

Subject: Re: inline links (Re: Online help access question)
From: Kathleen MacDowell <kathleen -dot- eamd -at- gmail -dot- com>
To: Robin Whitmore <rwhitmore -at- weebly -dot- com>
Date: Mon, 3 Oct 2016 15:57:24 -0500

The level of user is always there to consider. It's best if you can set up
separate materials for each level, but that's rarely possible. What I've
done in the past, for complex situations, is provide an overview of steps
so that people can go to the necessary section, whether they're novices or
experts. Section headers make it easy to make it clear. If it's electronic,
one could link to each section.

Note that I'm referring to complex situations with steps, not to general
types of documents.

Re links: I'm not totally against them. But there are situations I wouldn't
use them--I'd make sure the relevant info was spelled out where necessary.

Kathleen


On Mon, Oct 3, 2016 at 2:13 PM, Robin Whitmore <rwhitmore -at- weebly -dot- com> wrote:

> Kathleen,
>
> 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. This is the beauty of links. You don't have to
> click them if you don't need them. But if you start including ALL content
> that might be needed under every circumstance, the doc gets much to wordy
> to be useful, especially for more experienced users. While you might solve
> this with expand/collapse widgets, people will always click them if they're
> collapsed (they want to see what's hidden), and many users will need to
> collapse them if they're always open, which is an extra click and
> interrupts their flow.
>
> Links are basically harmless. They are short, and by now not something
> that causes readers to stop, as we are all accustomed to them, and they
> allow those who (for now) need more info to go get what they need.
>
> As for definitions and the like, IMHO the best UX is a popup with a
> definition, unless more complex conceptual information is needed.
>
> Also, I'm wondering what you feel the difference is between an
> "old-fashioned" See cross-reference and a link? In my mind, they serve the
> same purpose, and a link is much more efficient and less obtrusive.
>
> Enjoying this discussion-
> Robin
>
> On Mon, Oct 3, 2016 at 11:43 AM, Kathleen MacDowell <
> kathleen -dot- eamd -at- gmail -dot- com> wrote:
>
>> 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
>>
>> On Mon, Oct 3, 2016 at 12:36 PM, <mbaker -at- analecta -dot- com> wrote:
>>
>> > Kathleen,
>> >
>> >
>> >
>> > While I donât disagree, I think there is something important to add
>> here.
>> > Links are not the only distracting thing that can occur in a document,
>> not
>> > the most distracting. The most distracting thing is probably a word or
>> > concept that you do not understand. In a critical procedure â one that
>> must
>> > be completed â a word or a concept that you do not understand is
>> obviously
>> > a critical problem. If the reader continues to perform the procedure
>> > despite not understanding critical information, there is a very obvious
>> > danger that they will do something wrong in the procedure.
>> >
>> >
>> >
>> > Then the question becomes, what is the best way to prevent them doing
>> the
>> > wrong thing based on a misunderstanding.
>> >
>> >
>> >
>> > If they recognize that they have misunderstood, they may decide to look
>> > elsewhere for information, which is obviously distracting in just the
>> same
>> > way that following a link is, but may ultimately be a good distraction.
>> >
>> >
>> >
>> > Providing a link is an obvious way to make this search for explanation
>> > easier for the reader, and to exercise control over which material they
>> use
>> > to clear up their misunderstanding.
>> >
>> >
>> >
>> > But there is more to it than this: the likelihood of a person performing
>> > any act is inversely proportional to its difficulty. Following a link is
>> > easier than doing a search or going to a library, which means it is more
>> > likely that the reader will try to clear up their misunderstanding
>> rather
>> > than carry on regardless.
>> >
>> >
>> >
>> > If we donât regard providing a link as an adequate solution to the
>> problem
>> > of someone misunderstanding a procedure, however, then we need to take
>> > other measures. There seem to be two alternatives:
>> >
>> >
>> >
>> > Â Address the subject of the possible misunderstanding inline.
>> > This can work on a small scale, but if there are many potential points
>> of
>> > misunderstanding, it will balloon up the text, making the procedure
>> harder
>> > to follow and introducing a whole new class of distractions.
>> >
>> > Â Prequalify users to perform the procedure. That is, restrict
>> > the performance of the procedure to people who have been certified in
>> > whatever skills and understanding are required. In this case, removing
>> the
>> > links makes sense because readers are supposed to understand all the
>> > required background and it would be better for them to stop when they
>> donât
>> > understand something than it would be for them to self-educate on the
>> fly.
>> >
>> >
>> >
>> > In short, links perform a function, and if we donât use them, we should
>> > ask ourselves what will substitute for the failure to perform that
>> > function, and what is the best way in the circumstances to make sure
>> that
>> > function is performed.
>> >
>> >
>> >
>> > Mark
>> >
>> >
>> >
>> > *From:* Kathleen MacDowell [mailto:kathleen -dot- eamd -at- gmail -dot- com]
>> > *Sent:* Monday, October 3, 2016 1:13 PM
>> > *To:* Mark Baker <mbaker -at- analecta -dot- com>
>> > *Cc:* Monique Semp <monique -dot- semp -at- earthlink -dot- net>; TechWR-L <
>> > techwr-l -at- lists -dot- techwr-l -dot- com>
>> > *Subject:* Re: inline links (Re: Online help access question)
>>
>> >
>> >
>> >
>> > Both of your comments are interesting and informative.
>> >
>> >
>> >
>> > To expand on what Mark said, then if one wants or expects a person to
>> read
>> > to the end of a document, one should not insert links. Not that the lack
>> > would keep them reading, but it wouldn't lead them astray.
>> >
>> >
>> >
>> > 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. If someone wants a refresher
>> on
>> > a later part of a process, they could do a search. All that suggests
>> ways
>> > in which such things should be organized, too, to assist the reader.
>> >
>> >
>> >
>> > Kathleen
>> >
>> >
>> >
>> > On Mon, Oct 3, 2016 at 12:01 PM, <mbaker -at- analecta -dot- com> wrote:
>> >
>> > Yes, I am familiar with Mysti's presentation and with the DITArati's
>> > common (though not universal) anti-inline-linking stand. The
>> anti-linking
>> > stand in DITA has a lot to do with the difficulties of managing inline
>> > links in reused content. DITA's link management mechanisms are curiously
>> > ill-suited to this task, which has led to many people using DITA turning
>> > against inline linking altogether.
>> >
>> > But there is something deeper at work here: a persistence of document
>> > thinking, which is particularly evident in a couple of the cons you
>> cite:
>> >
>> > * Statistics show that users tend not to return to a page after they
>> link
>> > away.
>> >
>> > Well, why would we expect them to? Document thinking says that readers
>> are
>> > supposed to read all the way to the end of the document so the document
>> has
>> > somehow failed if people follow a link and don't come back. But this is
>> > ridiculous. It is like suggesting that a road should not have junctions
>> > because people make take a side road and not travel all the way to the
>> end
>> > of the main road. Readers have an information destination and there is
>> no
>> > reason to think that one document can (or should try) to take them from
>> > their precise and individual starting point all the way to their precise
>> > and individual end point.
>> >
>> > * Statistics show that most links simply aren't clicked.
>> >
>> > And drivers don't take most turns in a road. But some drivers take each
>> of
>> > the turns, and the road network as a whole relies on all of those turns
>> > being available to take. (This is not to say that there are never
>> > unnecessary links, any more than that there are never unnecessary road
>> > junctions that lead nowhere. Often people link at random rather than
>> having
>> > a consistent well thought out linking strategy.) Document thinking rears
>> > its head again here: every part of the document is supposed to be used
>> by
>> > every reader. If a link is not clicked, the reader is not consuming the
>> > whole of the document.
>> >
>> > But this idea that the reader is supposed to consume the whole document
>> > and nothing but the document is bonkers. It was always bonkers, but in
>> the
>> > paper world, where getting from one document to another was relatively
>> > difficult, there was some justification for thinking and designing this
>> > way. But in a hypertext world you can get anywhere instantly. Hypertexts
>> > are nodes in a network and readers get what they need from a successful
>> > traversal of the network, not from the consumption of the whole of a
>> single
>> > document.
>> >
>> > Mark
>> >
>> >
>> > -----Original Message-----
>> > From: techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com [mailto:
>> > techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of
>> > Monique Semp
>> > Sent: Thursday, September 29, 2016 5:08 PM
>> > To: TechWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
>> > Subject: 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 mbaker -at- analecta -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
>> >
>> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> > Visit TechWhirl for the latest on content technology, content strategy
>> and
>> > content development | http://techwhirl.com
>> >
>> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> >
>> > You are currently subscribed to TECHWR-L as kathleen -dot- eamd -at- gmail -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
>> >
>> >
>> >
>> >
>> >
>> > --
>> >
>> > Kathleen MacDowell
>> > kathleen -dot- eamd -at- gmail -dot- com
>> >
>>
>>
>>
>> --
>> Kathleen MacDowell
>> kathleen -dot- eamd -at- gmail -dot- com
>> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> Visit TechWhirl for the latest on content technology, content strategy
>> and content development | http://techwhirl.com
>>
>> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>
>> You are currently subscribed to TECHWR-L as rwhitmore -at- weebly -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
>>
>
>
>
> --
> *Robin Whitmore*
> Senior Tech Writer
> Weebly
> 460 Bryant Street, #100
> San Francisco, CA 94107
> rwhitmore -at- weebly -dot- com
>



--
Kathleen MacDowell
kathleen -dot- eamd -at- gmail -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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


Follow-Ups:

References:
RE: inline links (Re: Online help access question): From: mbaker
Re: inline links (Re: Online help access question): From: Kathleen MacDowell
RE: inline links (Re: Online help access question): From: mbaker
Re: inline links (Re: Online help access question): From: Kathleen MacDowell
Re: inline links (Re: Online help access question): From: Robin Whitmore

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