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.
When I use the term version, I mean it in the CMS sense i.e.
another iteration of the same topic.
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.
But the original isn’t updated with push conref either
– only the output is updated. You could still end up with lots of
competing topics with different partial pictures. If you want a single topic
with the complete picture, then you have to update the original topic.
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).
Yes, agreed, it could be pretty messy.
IBM DITA Architect and Classification Schema PDT Lead
So the use case be summarized
- Product A has a deliverable that contains topic A with 7
- 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,
From: Michael Priestley [mailto:firstname.lastname@example.org]
Sent: April 17, 2007 09:59
To: Michael Gannon
Subject: Re: [dita] 12015 - Conref Push
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
IBM DITA Architect and Classification Schema PDT Lead
- 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
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: