OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita-adoption message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: conref push scenario

Here is the conref push scenario that I sent to Sowmya ...

-------- Original Message --------
Subject: Re: [dita-adoption] Groups - DITA 1.2 feature article: conref push (conref_push_2.doc) uploaded
Date: Mon, 12 Oct 2009 08:07:27 -0400
From: Kristen James Eberlein <keberlein@pobox.com>
To: Sowmya Kannan <Sowmya.Kannan@Sun.COM>
References: 20091011233552.20887.qmail@eos.oasis-open.org"><20091011233552.20887.qmail@eos.oasis-open.org> 4AD2AB4C.5050102@sun.com"><4AD2AB4C.5050102@sun.com>

Good question. I think conref push is going to be used often when topics are reused between different authoring teams or product documentation groups. Here's one scenario:

There are two information sets (A and B), each of which is owned by different teams. The A information set is for an integrated development environment (IDE); the B information set is for a product that use the IDE as base for their product. The A information set contains a topic about "Installing the IDE."

Now, the process for installing the IDE will be almost identical for both A and B. However, there will be one extra GUI window that people installing B will encounter.

Version whatever of A gets released to market in 1Q2010. Product B won't be released for several months, and the contents of the B-specific GUI window are not nailed down. The writing team for A does know, however, that team B will need to reuse the installation topic and so makes sure that it has the necessary @id attributes.

This enables team B to later push a step into that installation topic.

Sure, there are other ways that this could be handled:

  • Team B could create a new installing topic, and then copy-and-paste content from the team A installation topic. (Yuck.)
  • Team B could create a new installing topic, and then conref content in from the team A installation topic.
  • The original installation topic could have contained the B-specific material which could be filtered out when team A builds the information set. (This does assume that the B-specific material could have been written at the same time as the A material.)
Does this help? Do you think that the article needs to have a handful of scenarios for when conref push is going to be most useful?


Sowmya Kannan wrote:
4AD2AB4C.5050102@sun.com" type="cite">Hi Kris,
Great article on conref push!
Would it be possible to add a few scenarios where an author would use a conref push as opposed to solving the problem in some other way? For example,  if all steps in topics X, Y, and Z  already contain the @id attribute, then creating a conref push would be an easy way to add a new step at  a specific location in these topics. But if the topics X, Y, and Z lacked the required @id attributes and I had to go in and add them to support conref push to include a a new step, can't I just use a vanilla conref in each of these topics to include the additional step.
Hope I did not completely confuse the issue:-).


keberlein@pobox.com wrote:
The document revision named DITA 1.2 feature article: conref push
(conref_push_2.doc) has been submitted by Kristen Eberlein to the OASIS
DITA Adoption TC document repository.  This document is revision #1 of

Document Description:

View Document Details:

Download Document:  http://www.oasis-open.org/committees/download.php/34627/conref_push_2.doc

This document is revision #1 of conref_push.doc.  The document details page
referenced above will show the complete revision history.

PLEASE NOTE:  If the above links do not work for you, your email application
may be breaking the link into two pieces.  You may be able to copy and paste
the entire link address into the address field of your web browser.

-OASIS Open Administration

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]