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.
Subject:RE: References a later chapter From:"Wilcox, Rose (ZB5646)" <Rose -dot- Wilcox -at- pinnaclewest -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 19 Sep 2002 14:45:40 -0700
John Posada writes:
<<
You do it with Appendix, no?
Refer anywhere to anywhere. Who cares if some professional technical writers
have a problem with it...users don't have a problem with it.
>>
Nothing wrong with references within a document. The way I was taught years and years ago was "avoid unnecessary branching". In other words, as a reader, I'm trying to work through a procedure that requires me to continually leaf through the manual in order to complete it. As a writer, I want to avoid putting the reader into that sitch.
That's different than simply referring to other material for reference purposes.
However what Evan is saying he wants to do is:
<<
Chapter One - Section One
1. Do this.
2. Set the Rate Book status to "Under Construction" (see Chapter 2 -
Section 2 for help).
3. Then do this.
>>
Although I don't know enough to say, it does look a little like unnecessary branching. It might be okay if setting the Rate Book status is done over and over in many processes and it saves a lot of time to concisely describe it elsewhere. The user may learn it through the constant repetition and then the branching wouldn't apply except for the first through times through the first few processes.
On the other hand, if the process could be described here and isn't repeated elsewhere, I would tend to include it "in-line" for the convenience of my reader.
Evan wants to "avoid duplicating a section that is later in the manual (and has to
stay there)." I don't know why the constraint exists for the information to stay later in the manual. I don't know if it is a political or time or project consideration or a design-driven consideration.
I think this one is a toss-up without more information. One branch doesn't necessarily make the manual unusable. On the other hand, I don't know how long the omitted material is and what makes it so hard to duplicate it.
The only comment I want to make here is that if you do it a lot, you might need to re-think your documentation design.
Rosie Wilcox
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Enhance, optimize and automate your FrameMaker-to-PDF workflow with TimeSavers:
Define all PDF features in your source FrameMaker files ONCE, distill MANY.
Bookmark Controller, Link Controller, UnBloat & more : http://www.microtype.com
Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever! 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.
