Variables vs Cross-references vs Text Insets [WAS: Hiding Pages?]

[nancy carpenter]

This might work better than text insets.  I use text insets for definitions
of fields on screens and for introductory paragraphs that are used in more
than one chapter.  Is there a limit to how much text you can insert with a
cross reference?  My introductions often are two or three paragraphs.

Nancy Carpenter
Lead Technical Writer
GENCO Distribution System
100 Papercraft Park
Pittsburgh, Pennsylvania 15238


|---------+------------------------------------------------------->
|         |           eric.dunn at ca.transport.bombardier.com       |
|         |           Sent by:                                    |
|         |           framers-bounces+carpentn=genco.com at lists.fra|
|         |           meusers.com                                 |
|         |                                                       |
|         |                                                       |
|         |           06/09/2006 09:58 AM                         |
|         |                                                       |
|---------+------------------------------------------------------->
  >----------------------------------------------------------------------------------------------|
  |                                                                                              |
  |       To:       "Ridder, Fred" <fred.ridder at intel.com>                                       |
  |       cc:       framers at frameusers.com                                                       |
  |       Subject:  Variables vs Cross-references [WAS: Hiding Pages?]                           |
  >----------------------------------------------------------------------------------------------|




"Ridder, Fred" <fred.ridder at intel.com> wrote on 06/08/2006 11:57:39 AM:
> In a situation where only the name changes, I find that it is *much*
> more maintainable to use a variable for the product name because
> you only have to make a change in one place (the variable's value
> definition) when one of the names changes or when a new variant
> is added to the list.

Personally, I don't like conditional text. Usually it gets far too complex
very quickly and you're hobbled by the limitation of OR logic for
overlapping conditions.

But, are variables the right answer? Why not Xrefs instead?

Perhaps this idea isn't terribly Earth shattering, but it came to me in a
flash and I've been using it successfully for some time now. The idea
struck me as more of a 'DUH' kind of realisation when I implemented it,
but after giving a FrameMaker class, I was amazed at how foreign the idea
seemed to so many.

The situation was this: hundreds of components, multiple ways of writing
their descriptions, abbreviations, and specifications which led to an
unmanageable mass of variables.

So, I turned to cross-references.

A stand-alone document contains a three column table.
Column 1 - CB Number
Column 2 - CB Placard
Column 3 - Complete description

ex:
CB1     LIGHTING        CB1, LIGHTING

Three cross-reference formats are used:
1 - CBNumber
2 - CBPlacard
3 - CBPlacard (Num)

So, depending on the requirements I can include CB1, LIGHTING, or LIGHTING
(CB1) in my documentation.

If the placard or information changes, I change the source document and
that's it. A generate update of all books ensures the data is correct.

I've actually begun using the same approach for terms and equipment names.
Any text that needs to maintain consistency is grouped with like terms in
a file.

So three HUGE advantages IMO. First, no need to maintain a MIF snippet of
variables or using a script/plug-in to import user variables only (because
invariably, one or more of the system variables are defined differently
for different sections/files). Second, instead of hundreds of variables, I
have 3 Xref formats. Third, generating and updating is already a step in
the publishing process. So, the step of importing variables is skipped and
not there to be forgotten.

What are the downsides? Well, so far nothing. But I have an itch in the
back of my skull concerning Xrefs and character formatting that I just
can't shake. Something as to whether character formatting applied in the
source (all character tagging is done using catalogue formats common to
source and destination) is kept in the destination or not...

Anyone know what I should be worrying about?

Eric L. Dunn
Senior Technical Writer

_______________________________________________________________________________________________________________


This e-mail communication (and any attachment/s) may contain confidential
or privileged information and is intended only for the individual(s) or
entity named above and to others who have been specifically authorized to
receive it. If you are not the intended recipient, please do not read,
copy, use or disclose the contents of this communication to others. Please
notify the sender that you have received this e-mail in error by reply
e-mail, and delete the e-mail subsequently. Please note that in order to
protect the security of our information systems an AntiSPAM solution is in
use and will browse through incoming emails.
Thank you.
_________________________________________________________________________________________________________________



Ce message (ainsi que le(s) fichier/s), transmis par courriel, peut
contenir des renseignements confidentiels ou protégés et est destiné à
l?usage exclusif du destinataire ci-dessus. Toute autre personne est par
les présentes avisée qu?il est strictement interdit de le diffuser, le
distribuer ou le reproduire. Si vous l?avez reçu par inadvertance,
veuillez nous en aviser et détruire ce message. Veuillez prendre note
qu'une solution antipollupostage (AntiSPAM) est utilisée afin d'assurer la
sécurité de nos systems d'information et qu'elle furètera les courriels
entrant.
Merci.
_________________________________________________________________________________________________________________



_______________________________________________


You are currently subscribed to Framers as carpentn at genco.com.

Send list messages to framers at lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/carpentn%40genco.com

Send administrative questions to lisa at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.