RE: Conditional content - what do you do with it?

Subject: RE: Conditional content - what do you do with it?
From: "Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com>
To: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 10 May 2010 15:36:38 -0700

Like other HATs, Help & Manual(H&M) enables you to conditionally include
and exclude whole topics as well as text. What content is included or
excluded depends on what conditions you have selected in your manual
build or build script.

Page properties for individual pages display in which builds a page is
included, and you can set conditional tags for several pages
simultaneously. For text, H&M uses tags to denote conditional text, and
the text itself is never effaced in any way. It features IF, IFNOT,
ELSE, and ENDIF tags. Included in the tag is the name of the condition.
For example, <IF INSTALLGUIDE>This is text that is conditionally
included only when the INSTALLGUIDE condition is selected for a
build.<ENDIF> You can also have multiple includes. For example, <IF
INSTALLGUIDE,ADMINGUIDE,EVALGUIDE>This is text that is conditionally
included when INSTALLGUIDE _AND/OR_ ADMINGUIDE _AND/OR_ EVALGUIDE
conditions are selected for a build.<ENDIF> You can also create
conditional tags that include or exclude text only when several
conditions are met. For example, <IF INSTALLGUIDE><IF ADMINGUIDE>This is
text that is conditionally included only when INSTALLGUIDE _AND_
ADMINGUIDE conditions are selected for a build.<ENDIF><ENDIF>.

H&M includes several default built in conditions (HTML Help, Web Help,
PDF, etc.) and enables the user to create as many custom conditions as
he needs.

You can tag individual words (or even characters) within paragraphs.
However, this isn't recommended if there is any chance that your docs
will need to be translated. My docs probably will need to be translated,
so where I previously had cleverly constructed sentences with certain
words omitted from various builds, I now generally have parallel
sentences (and, in some cases, parallel paragraphs).

>From a single source, I build several guides in Web Help and PDF for
five different but overlapping products.

Leonard



-----Original Message-----
From: techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
om] On Behalf Of McLauchlan, Kevin
Sent: Monday, May 10, 2010 1:50 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Conditional content - what do you do with it?

Back in the day, I used conditions in simple ways in FrameMaker.

More recently, but still several years ago, I used conditional
text in RoboHelp, and started getting a little fancy with it.

That eventually bit me in the butt, and necessitated a huge
amount of work in a short time to fix, to my satisfaction.
So I began easing myself out of the use of conditions,
even as I was switching from RH to Flare as my HAT.

Even so, I still had conditions in place, especially in
help sets that had not been updated in a while.

While I found that I could trust conditions to behave as
expected in Flare, I still found the other problem that had
annoyed me. Both RH (as I recall....) and Flare use colored
cross-hatching on text, and colored icons in ToCs and file
lists, to show where a given condition is applied.

When text is given one or two conditions, that's manageable,
but when a block of text might have four or more cross-hatchings
applied to parts or all, it becomes visual mush.

My color perception is reasonably good; I can always pick
out the 'hidden' numbers and letters in the tests.
I'm not officially visually handicapped - I just have "the
biggest honkin' floaters <my ophthalmologist has> seen in
<his> twenty years of practice!" - but still, I find that
the visual clutter can be daunting. Makes reviewing
and editing a misery. But part of an editing pass is to
determine/confirm which bits should be included/excluded in
this-or-that circumstance. So some of my topics are
about as easy to read in WYSIWYG source as are government
documents that have gone through... ahem... redaction.
Makes ransom notes easy on the eyes, by comparison.

Maybe that's just me.

So what is the experience of others, and what do you
normally do with conditions? Do you allow them to
overlay? Do you break out text-and-illustrations to a
new page or snippet as soon as it looks like more than
one or two conditions might need applying if the content
remained on the original parent page?

Other?

For that matter, how is conditional text/content
depicted in the interface of HATs other than RH and
Flare?

I find that after you've hit three layers of colored
cross-hatching, you are pretty much looking at brown.
But then, that's what I said about the curtain material
my wife picked out "It's got this bit of gold to pick
up this accessory, and this thin red stripe to pick up
the furniture fabric and that other little stripe to
catch the painting behind the sofa ..."
"But Dear, from more than three feet away, it all
looks brown to me."
"Brown!? That's what you say about tweed - 'it
all looks grey' to you.
"Well, yeah. It could have a million colors in it,
but step back ten feet and every tweed jacket and
skirt in the world is grayish brown... or brown-ish
gray." :-)

What works out there? For HATs and conditions, I
mean, not fabric selection.

How small a unit do you conditionalize?
Do you actually go within-page to apply conditions
on chunks of text, or do you confine your conditions
to the topic-page-file level?

I feel that I should be getting much more use and
convenience out of the conditional feature.
One of the product lines that I document has five
major products that share a good 30 percent of
their content globally, while several pairs within
the group would have as much as 70-percent commonality.


Kevin McLauchlan
Senior Technical Writer
SafeNet, Inc.
--

The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com


- Use this space to communicate with TECHWR-L readers -
- Contact admin -at- techwr-l -dot- com for more information -


---
You are currently subscribed to TECHWR-L as
Leonard -dot- Porrello -at- soleratec -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit
http://lists.techwr-l.com/mailman/options/techwr-l/leonard.porrello%40so
leratec.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com


- Use this space to communicate with TECHWR-L readers -
- Contact admin -at- techwr-l -dot- com for more information -


---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

References:
Conditional content - what do you do with it?: From: McLauchlan, Kevin

Previous by Author: RE: Reusing/Managing Requirements Across Multiple Projects
Next by Author: RE: Context-sensitive - menu-item topic or... Clippy?
Previous by Thread: RE: Conditional content - what do you do with it?
Next by Thread: RE: Conditional content - what do you do with it?


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


Sponsored Ads