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.
> So my question is, in the online version, should I repeat the instructions
> for opening the Whatzigig page in each topic? Should I include a link to
> those instructions in each topic? Should I NOT assume the reader can't
> figure this out? What is the BEST way when I'm single sourcing?
To give a "definitive" answer, I'd have to see the material. But here are
some things to consider.
If "opening the Whatzigig page" is something that can be conveyed in one
step, then I see no harm in repeating it multiple times. If your instruction
for that step begins with the words "To open the Whatzigig page", you've
given your user a nice cue for skipping the rest of the instruction if they
don't need it. Unneeded instructions are not annoying if they are easily
"skipable." Keep in mind that your user isn't likely to be reading ALL the
instruction sets anyway, but just the one that he or she needs at that
moment. Therefore, what seems to you like "repetition" will not even be
If the situation is such that you feel certain that more than 80% of your
readers will already know how "to open the Whatzigig page", and will find the
repetition more annoying than helpful, then you can probably leave it out.
But make sure the remaining 20%, who need the instruction, have an easy way
of finding it. You can do this with a hyperlink or a cross-reference.
I hope you won't mind if I do a bit of preaching here and remark that "What
is the BEST way when I'm single sourcing" is one of those questions that
borders on letting the tail wag the dog. Don't let your tool-set drive your
information design. It is "what is best for my users" that really matters.
I've had this issue come up in my writing team, and I've caught myself doing
the same thing. It is almost disturbingly easy sometimes to let consideration
of the writers' convenience take precedence over that of the users. Just a