RE: Too many hyperlinks in a topic?

["McKinney, Suzanne" <smckinney -at- eei1 -dot- com>]

Rene wondered:

	<<I'm reviewing a (java)help document that  has been critised as 
	having excessive hyperlinks in each topic, such that readers 
	are easily diverted and become 'lost' from the original topic 
	that they were reading.

	A silly question, I admit, but is there is consensus or general 
	rule of thumb as to what consititutes "excessive hyperlinks"?

	Is the answer to simply reduce the hyperlinks?>>

I have been successfully using a strategy that involves the following:
	1. Unless completely critical at the moment, links are at the end under See also or Related procedures.
	2. Each topic has a link at the top to its parent topic, the idea being that this will prevent users from getting lost.

So far I have no complaints (2 years of a help system with users from a mixed background of PC experience.

I think it's very important to always provide the way back. I saw that first at a help conference some years ago and began using it in my last job, where it's still in use (several years later).

Sue McKinney
smckinney -at- eei1 -dot- com

------------------------------

Message: 3
Date: Sun, 17 Sep 2006 11:44:30 -0400
From: Geoff Hart <ghart -at- videotron -dot- ca>
Subject: Too many hyperlinks in a topic?
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, e-letter
	<inpost -at- gmail -dot- com>
Message-ID: <6B5666FF-2E51-4C02-9249-E4F4BA9F71A5 -at- videotron -dot- ca>
Content-Type: text/plain; charset=ISO-8859-1; delsp=yes; format=flowed

René wondered: <<I'm reviewing a (java)help document that  has been  
critised as having excessive hyperlinks in each topic, such that  
readers are easily diverted and become 'lost' from the original topic  
that they were reading.>>

If the people doing the criticizing are representative of the actual  
readers of the document, then it pays to listen carefully to what  
they're saying. Even if they're not, it still pays to listen: they  
may be wrong, but you won't know that until you understand why  
they're complaining and whether it's a good reason. (When in doubt,  
assume the reader knows more than you do about their own needs. <g>)

<<A silly question, I admit, but is there is consensus or general  
rule of thumb as to what consititutes "excessive hyperlinks"?>>

Yup: they're excessive if there are more of them than necessary. <g>  
Sorry to be a bit facetious, but that's really the only useful answer  
to your question. That being said, the problem becomes one of  
determining how many are necessary:

<<Is the answer to simply reduce the hyperlinks?>>

It depends. <g> No, really. If the hyperlinks are simply additional  
useful information that some reader might possibly be interested in,  
then gather them together at the end of the topic as a series of  
"related topics". If you need to understand the contents of each  
hyperlinked topic before you can understand the current topic, then  
you should consider integrating that information within the current  
topic rather than forcing readers to leave the current topic.

If the links are to material that is of general interest, then you  
should gather it into a single "what you need to understand before  
reading any further" topic, and add a line such as the following at  
the start of the current topic: "If you do not already understand  
[description of the general information required to understand the  
current topic], read [hyperlink] first." I like to open the new topic  
in a new window so that closing the new window immediately returns  
readers to their original context and that it's easy to become "lost  
in hyperpace" if you follow a fruitless series of links in a single  
window; the "back" button won't always help. Recognizing that many  
users abhor an endless spawning of new windows, I won't open more  
than one new window: those who want more can do this themselves.

As a general rule, any help topic should begin with a brief overview  
of key context: information that tells the reader they've found the  
correct topic (ideally, the title of the help topic should be all  
that's necessary). Next, provide an overview of any crucial context  
that won't fit in the title: steps that must be completed before you  
begin pondering the steps in the current topic, warnings of various  
degrees of seriousness, information on who can and cannot perform the  
steps in the current topic (e.g., if you need administrator rights or  
an advanced degree in physics), and a discussion of the various  
alternatives (use approach A if..., use approach B if...). Continue  
with links to anything that readers should understand before they  
read any further, then present the actual text of the current topic.  
Conclude with links to information that is useful (to get the most  
out of the current information) but not essential. Essential  
information belongs right in the topic.

For longer or more complex topics broken into several sections,  
repeat this structure for each subtopic presented in the same window,  
and if there are several of these, consider starting the window with  
the text "This help topic contains the following sections", followed  
by hyper links to each section. There's some debate about the use of  
these mini-TOCs, but I personally find them so useful I can't imagine  
anyone objecting much to their presence. (Possibly a failure of  
imagination? <g>)

<<Should the document change from object orientated (now) to more  
task orientated (future)?>>

If it's a reference manual, then focusing on the meaning and use of  
each object in the interface is perfectly appropriate. If it's a user  
manual, focus on the tasks, and provide links to any reference  
material that is incidental to the tasks. Any reference material that  
is crucial to performance of a task and that readers can't be  
expected to already know belongs directly inside the task description.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --

Geoff Hart   ghart -at- videotron -dot- ca

(try geoffhart -at- mac -dot- com if you don't get a reply)

www.geoff-hart.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -




------------------------------

Message: 4
Date: Sun, 17 Sep 2006 11:40:08 -0400
From: "David Castro" <thejavaguy -at- gmail -dot- com>
Subject: Re: too many hyperlinks in a topic?
To: e-letter <inpost -at- gmail -dot- com>
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID:
	<8319ca490609170840n30705f33nbd87f2a38802eede -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed

On 9/16/06, e-letter <inpost -at- gmail -dot- com> wrote:
> I'm reviewing a (java)help document that  has been critised as having 
> excessive hyperlinks in each topic, such that readers are easily 
> diverted and become 'lost' from the original topic that they were 
> reading.
>
> A silly question, I admit, but is there is consensus or general rule 
> of thumb as to what consititutes "excessive hyperlinks"?

Earlier this week, I emailed someone who said she worked on Borland's online help to ask her if she was at all responsible for the overview topics in the online help for Delphi 3. They were heavy with links, taking you to more detailed explanations of each of the overview topics that were being briefly covered in the overview topic. I LOVED those topics, as they gave me a starting point that centered around a single topic; the links were frequently were all over the place in the TOC (I guess it was more like an index than a table of contents in that regard). I have created the same kind of link-heavy overview topics in online help that I've written for more than one product.

That said, I can see where you might not want to have a bunch of links in, say, a procedural topic. You don't want readers to move to a new topic while they're in the middle of a set of steps. In those topics, you might consider moving the links down into a See Also section at the bottom of the topic.

-- 
-David Castro
 thejavaguy -at- gmail -dot- com


------------------------------

Message: 5
Date: Sun, 17 Sep 2006 11:42:28 -0400
From: Ray Pichulo <rayp -at- rplaboratory -dot- com>
Subject: Re: Pubsnet Question: Real or Bogus?
To: techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID: <450D6CE4 -dot- 8090404 -at- rplaboratory -dot- com>
Content-Type: text/plain; charset=us-ascii; format=flowed

Apparently someone, somewhere, has a virus or trojan. Notice that all of 
the spam is dated Sept 5. I thought it was because their listserver is 
open and dutifully forwards all the incoming messages to the list. But 
you aren't subscribed, so that shoots down that theory.

Unlike real spam, this always has the same "FROM" address, so it's easy 
to block. Worked 100% for me. :)

Al Landis wrote:

> Does anyone know what Pubsnet is/does? I have been receiving 
> unsolicited e-mail from them like crazy. I've tried to unsubscribe, 
> not that I ever did subscribe... are they legit?
>
> - Al




------------------------------

Message: 6
Date: Sun, 17 Sep 2006 12:23:14 -0400
From: Steven Jong <SteveFJong -at- comcast -dot- net>
Subject: Re: Picture behind Text in Word
To: TECHWR-L Digest <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID: <E420A697-7803-4A3E-BB4F-743AAC731485 -at- comcast -dot- net>
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed

On Sep 15, 2006, at 2:38 PM, CGiordano -at- EvergreenInvestments -dot- com wrote:

> Have you tried opening the header/footer view and placing the
> picture?  If
> you float the picture rather than using inline, it should work  
> anywhere on
> the page.  I know it's not the correct way, but any port in a storm!

I have learned the hard way not to embed anything extra in Word  
headers or footers, particularly if others will be using your files.  
Old headers and footers can seemingly resurrect themselves when  
section breaks are inserted, leaving someone down the line wondering  
where the strange text came from and how to get rid of it.


------------------------------

Message: 7
Date: Sun, 17 Sep 2006 15:48:14 -0400
From: "Bill Swallow" <techcommdood -at- gmail -dot- com>
Subject: Re: R-E-S-P-E-C-T me! (Please!)?
To: "Mike Schmidt" <mschmidt -at- weathercentral -dot- tv>
Cc: "Poshedly, Ken" <PoshedlyK -at- polysius -dot- com>,	TECHWR-L
	<techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID:
	<375e3cb30609171248k713be4b1l2913fbce8e8e2fa7 -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed

Well, the definition of a technical writer is quite broad at this point in time. As fields and technologies have broadened, so has out reach. I don't care whether or not the general public understands what I do. So long as my employer and my indusry does, I'm happy.

On 9/15/06, Mike Schmidt <mschmidt -at- weathercentral -dot- tv> wrote:
> How 'bout when someone - anyone - asks you what you do. You tell them 
> and they repeat back to you that you're a programmer or "software 
> engineer" or something.
>
> Lots of the general public doesn't even know what a technical writer 
> is...
>


-- 
Bill Swallow
HATT List Owner
WWP-Users List Owner
Senior Member STC, TechValley Chapter http://techcommdood.blogspot.com avid homebrewer and proud beer snob "I see your OOO message and raise you a clue."


------------------------------

_______________________________________________
You are currently subscribed to 
TECHWR-L.
To unsubscribe send a blank email to 
http://lists.techwr-l.com/mailman/listinfo/techwr-l
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit 
http://www.techwr-l.com/techwhirl/ for more resources and info.

End of TECHWR-L Digest, Vol 11, Issue 18
****************************************
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.