Repeat text or refer to it?

This forum is for the discussion of the business and craft of writing help. For example writing style, choices of HTML Help or WinHelp or browser-based and so on...

Moderators: Alexander Halser, Tim Green

Post Reply
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Repeat text or refer to it?

Unread post by Dean Whitlock »

I'd like opinions and reasons on this question, please:

I have material that appears on more than one program screen (data fields that are on both the Create New dialog and the Review/Modify dialog). In some cases, the Review/Modify dialog has additonal fields pulled in from elsewhere, but the basic info is the same.

I deliver help in two formats, browser-based and PDF, which is used to produce printed manuals. I've been using hyperlinks to refer from the Review/Modify topic to the field descriptions of the basic info in the Create New topic. This works just fine in BB help. In PDF help it results in a page icon referrer.

I have recently tried putting the basic info in an invisible topic, which I embed in both the Create New and Review/Modify topics. Now all the information is right at hand, no linking required. This works just fine in both BB help and PDF help, but (and here's the rub) my PDF file is now significantly longer. (Since the images are reused in BB help, the increase in file size due to additional text in the Review/Modify html files is not significant.)

My question is this: Does the increase in PDF file size and printed manual page count outweigh the advantage of the user not having to flip a few pages back to find the basic info? My concern is that the user won't bother to print the longer manual (and will call support all the time instead) or will print it but be intimidated by the length and won't ever open it (thus calling support all the time).

Thanks,
Dean
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Repeat text or refer to it?

Unread post by Martin Wynne »

Hi Dean,

Don't forget that you can put conditional text flags round an embedded topic.

So you can use both options -- embedded in Browser (no clicking off the page), and a page referrer in PDF (smaller file).

Martin.
Jonathan S
Posts: 163
Joined: Mon Oct 03, 2005 5:58 pm

Unread post by Jonathan S »

One other aspect that I've seen in our documentation department is that when the same block of text is used in several spots some users start feeling like they're not getting anything new from their extra reading. I'd lean towards the referrers, especially if the information is basically identical.

If there is a way to put the information in the place they are more likely to go to first, then when they get to the other topic, it can give a brief description that also indicates that control A works much (or exactly) like control B (with conditional tags, if necessary, for non-pdf formats) and say, "for more detail, see the full control A description.

Of course, if you can't determine which topic is more likely to be learned first, you're in a crap shoot as to where to put it, or just put it in the place it first appears in the TOC.

My opinion: If it takes longer to read it than to look it up, refer to it; if it takes longer to look it up than to read it, just put it in the text. How's that for vague? :wink:

If you come up with something that really works well, let us know!

Jonathan
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Repeat text or refer to it?

Unread post by Martin Wynne »

Hi Dean,

The big problem with hyperlinks (and this applies generally, not just in Help) is that having jumped to the other location, there is no mechanism there to say "ok, you've read all you came here for, now go back where you came from".

What more likely happens is that you continue reading the other topic, come upon another link and click that. In no time you have jumped several times and completely lost the thread you started on -- both mentally and visibly.

I much prefer everything to be in a single page, even if it does mean duplication. When I come across a link in mid-text there is always a moment of irritation when I think "if it's important, why not just tell me? why send me off to find it? if it's not important why distract my train of thought?".

Using embedded topics can save a lot of such jumping to and fro, I think it's a great feature of H&M. Links are best at the start of a topic or at the end. "Before reading this, make sure you know about...". "After reading this, there is related info at...".

Martin.
Jonathan S
Posts: 163
Joined: Mon Oct 03, 2005 5:58 pm

Unread post by Jonathan S »

Dean,

How much ability do you have to do usability testing? Can you get your audience (or people typical of them) to sit down and try things a couple of different ways? Given that my preference and Martin's preference seem to be fairly different, if the resources are there, it might be worth finding out from your users their preferences.

Of course, you may find that there's a fairly even split, or even preferences we haven't considered, and like most things, you'll make some people happy and some not so much. :roll:

Good luck!

Jonathan
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

I'm leaning toward Martin's suggestion (using embedded topics and conditionals) for a couple of reasons:

1. I, too, feel irritated if I have to go searching for the information.

2. I, too, have gotten lost following links (though the help topics I'm working on seldom if ever have situations where a link leads to another link leading to still more links).

Underlying both of these is the simple fact that most people (myself included) are usually in a rush and don't have the time to go searching. In my experience, if they can't find it on the first try, or at most the second, they give up and call support or try to work it out on their own, with sometimes messy results.

The above statement is anecdotal, of course. Jonathan's suggestion regarding usability testing is certainly apt; testing would be the only way to see what's really happening in user-land. Unfortunately, I don't have the resources or the support from management. Unless some kind forum member can point me to testing results I'll have to make my guesses and press on, hoping for the best.

Thanks,
Dean
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Unread post by Martin Wynne »

Dean Whitlock wrote:I'm leaning toward using embedded topics and conditionals
Hi Dean,

This raises an interesting question. Will the new "toggle" feature in H&M4.2 allow an embedded topic and/or conditionals in the expanded part? Tim?

If so it would add a further option to the "link or embed" debate.

Martin.
Post Reply