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.
Funny you should mention that - I had the EXACT same problem for a large
single source user manual/online FrameMaker document.
Originally, I went with the "cross reference" approach. That is, the
first line of the procedure linked to another procedure, which in turn
had a first step that linked to another procedure, and so on and so on
until you got to the very first, top-level procedure. In other words, I
had unknowingly created a monster. Sometimes you have to create a beast
before you can slay it - that's how you learn.
Realizing my mistake, I went back and removed most of the
cross-references and replaced them with the actual steps. Yes - this has
its disadvantages. There is more work required for the writer in
maintaining the document, and the document becomes larger. But I think
the advantages outweigh this - in the end, I had procedures that were
far easier for the end user to follow.
And isn't helping the end user what tech writing is all about? (awh -
group hug!)
:-)
Andrew Brooke
abrooke -at- advancedutility -dot- com
"What the mind can conceive and believe, the mind can achieve."
W. Clement Stone
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
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!
---
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.
