When the products are from different
companies, or product B ships after product A, filtering is not an option.
Also, it's not a matter of creating
a new version of the topic in product A - it's a matter of updating the
original that already exists in the infocenter or on the customer's machine.
IE, product B installs on top of and updates product A. In turn,
after product B is installed, it's possible that product A will have a
fixpack that updates various things - so static builds of the content can't
give us what we want.
The range approach still creates a new
topic instead of pushing into the original topic - which means you now
have two copies of the topic in search results, etc. In other words, you
haven't updated the original, which is what's required - you've only managed
to add a correct copy that goes along next to the old one. The approach
also fails when product C etc. start wanting to add their configuration
steps as well - we end up with dozens of competing topics, each of which
contains only a partial picture - when what we want is a single topic that
gives the complete picture. This is a real scenario.
In addition to the issue of preserving
the original topic's identity (which creating multiple copies does not
do), there's the issue of tagging complexity - to add a single step to
an existing task, for example, I'd need to either use conref-with-delta,
or create a new topic that conrefs separately the original title, context,
prereqs, steps 1-5, steps 6-8, results, example, and related-links - and
accept that my conrefs will break if the original author deletes any of
those things. (Less of an issue with conref push since the original author
makes a deliberate decision to expose the target, and so knows the risks
of deleting it).
Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
So the use case be summarized
as follows:
-
Product A has a deliverable that contains
topic A with 7 steps
-
Product B wants a deliverable that contains
the same set of steps in topic A, with one extra in the middle
-
Products C –
Z potentially want deliverables that contain the
same set of steps in topic A, with arbitrary additions
Thanks for the explanation,
I have a better handle on
the use case now;
adding push conref still makes me nervous
however. Could
topic A
be updated
with all possible steps, and
conditional text used
to filter per product
- or would that
be too messy? My
vote would be for the solution
of using regular
conref with the additional
capability for ranges (as proposed in
12013). This keeps conref reuse simple
in the author’s mind –
pull (reuse)
the bits of information that you need
into your topic.
Just my 2c,
Michael.
From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: April 17, 2007 09:59
To: Michael Gannon
Cc: dita@lists.oasis-open.org
Subject: Re: [dita] 12015 - Conref Push
Hi Michael,
A common scenario today is in Eclipse infocenters/help systems, which are
assembled from plugins. You might have one plugin that holds the base docs
for a product, and then additional plugins provided by add-on components
or even other products that "plug in" to the original.
In this context, there may be certain topics in the base documentation
that require changes based on what components are added. For example, let's
say the base docs have a topic "Configuring security" with a
seven-step procedure. Product B adds a new set of capabilities that create
a new security exposure - which is easily addressed by adding a new step
in the middle of the existing procedure, using a conref push. This is possible
today in Eclipse XHTML output, but there's no easy way to express the intent
in DITA (you can specialize or use the outputclass attribute, but that's
not an architected solution it's a workaround).
The alternative of creating a new version of the "configuring security"
topic would be possible, but then you'd have two topics in search results
etc., and no way to guarantee users will read the right one. Even if you
somehow deleted the original, you'd still have all the dangling links pointing
to the original. If you say you want to create a new topic, reuse with
delta from the old, then rename the new to the old, the processing stream
gets pretty nasty, as well as the cognitive overload. For what it's worth,
this approach was my first thought as well, but it got complicated enough
that there was some strong pushback from the writers reviewing the proposal
and so I simplified to follow author intent more closely ("jam this
content there" vs. "create a copy of that and make this change
and copy it back").
As far as calling it conref, the implementation is certainly not final
- I'm not tied to calling it conref, although I'm not sure whether
there's more confusion by having conref push/pull or from having an additional
non-conref reuse mechanism.
Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
"Michael Gannon" <michael.gannon@xmetal.com>
04/17/2007 12:36 PM
To
<dita@lists.oasis-open.org>
[dita] 12015 - Conref Push
At first glance I’m against this proposal, but that may be due to my lack
of understanding. As I read it, the use case is that an author B can update
a topic that another author owns without having to update the topic itself.
Is this a common use case? Can author B not just update the topic him/herself?
Is creating a new version of the topic really that much of an issue? I
believe Michael P. mentioned in the meeting a couple of weeks ago that
a customer really needs this included in 1.2, so maybe I’m missing something
obvious.
Would the inclusion of 12013 in DITA 1.2 negate the need
for this? Author B could pull in bits of the original topic and add the
extra information around the bits. All of the current reuse techniques
in DITA are pull, and I think keeping it this way would be the simplest
way forward.
Also, if it has to be in, I think calling this conref is
a bad idea; two types of conref that do the opposite of each other seems
like it would introduce a lot of confusion for users.
The original proposal is here:
http://www.oasis-open.org/committees/download.php/15120/IssueNumber17e.html
Michael.
Michael Gannon
Software Developer
JustSystems Inc.
778-327-6352
michael.gannon@xmetal.com
www.xmetal.com