RE: [dita] 12015 - Conref Push

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

Title: 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