dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Re: [dita] 12015 - Conref Push
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: "Michael Gannon" <michael.gannon@xmetal.com>
- Date: Tue, 17 Apr 2007 12:59:02 -0400
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]