RE: [dita] 12015 - Conref Push

[Michael Priestley <mpriestl@ca.ibm.com>]

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

"Michael Gannon" <michael.gannon@xmetal.com>

04/17/2007 01:40 PM

To	Michael Priestley/Toronto/IBM@IBMCA
cc	<dita@lists.oasis-open.org>
Subject	RE: [dita] 12015 - Conref Push

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>

cc

Subject

[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