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.
Claire asked:
>>>>I am including a procedure for every element. Now here's the problem.
Within a number of these elements there is a lengthy sub-procedure which is
identical.
Should I document this sub-procedure fully for the first instance only and
cross-reference the user to this section for all other elements.
Or
Should I include the procedure in full every time it is required.
<<<<<
You've received some response that recommend a cross-reference for this
sub-procedure, and I strongly disagree. Put yourself in the place of the
user who's trying to figure out this procedure. Do you like
cross-references, or do you prefer not having to bounce around from page to
page, and just have the procedure spelled out for you in linear fashion?
Yes, this might make the resulting manual larger. So what? I doubt that
the size of a manual intimidates users. These books are rarely read like a
work of fiction (although some have elements of fiction in them:-) ), so the
fact that the same sub-procedure is duplicated in many places will likely
not be a sore spot with the user. They're opened when the user has to
figure something out. Make it as easy for them as possible.
BTW, some of my early user's guides used cross references within a
procedure. Upon re-editing for software updates I got rid of the cross
references and just repeated the sub-procedures where needed. The clients
commented that the new manuals were far more user friendly.
Paul Strasser
Windsor Technologies, Inc.
2569 Park Lane, Suite 200
Lafayette, Colorado 80026
Phone: 303-926-1982
FAX: 303-926-1510
E-mail: paul -dot- strasser -at- windsor-tech -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!
Order RoboHelp X3 in November and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
