Re: Repetition in Procedures

Subject: Re: Repetition in Procedures
From: "Andrew Brooke" <ABrooke -at- ADVANCEDUTILITY -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 26 Nov 2002 11:21:10 -0500


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

http://www.compuquick-consulting.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.


Previous by Author: Information Mapping definition
Next by Author: Placing TOC Entries into Separte Hyperlinked Table Cells to Show Links Between Processes
Previous by Thread: RE: Repetition in Procedures
Next by Thread: Posting my technical writer resume


What this post helpful? Share it with friends and colleagues:


Sponsored Ads