Re: [dita-adoption] conref push scenario

[Joann Hackos <joann.hackos@comtech-serv.com>]

Title: Re: [dita-adoption] conref push scenario

Here are two other scenarios:

1) Printer manufacturer has just discovered that Microsoft has changed a configuration in Windows that invalidates their instruction for installing the printer driver for the new machine. They need to issue a “patch” to the topic on their website explaining a workaround until they can update their driver. Within a few days, they will have the driver updated and will no longer require the patch. They do not want to change the source topic. A Conref push will allow them to input a temporary fix. [by the way, this actually happened but the manual was already printed. They had to open ever box in inventory and put in a flyer with the correction. However, the correction was only valid for about a week]

2) Company provides third-party documentation as part of their complete package to customers, in addition to their own documentation. All the content is in DITA including the third-party. They want to insert a specific warning into the third-party documentation that they provide to their customers without asking the third party to make the change for contractual reasons. Conref push should help this as long as the third party includes the @ids.

JoAnn


On 10/12/09 11:06 AM, "Kristen Eberlein" <keberlein@pobox.com> wrote:

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> <mailto:keberlein@pobox.com>   
 To:  Sowmya Kannan <Sowmya.Kannan@Sun.COM> <mailto:Sowmya.Kannan@Sun.COM>   
 References:  <20091011233552.20887.qmail@eos.oasis-open.org">20091011233552.20887.qmail@eos.oasis-open.org> <20091011233552.20887.qmail@eos.oasis-open.org">mailto:20091011233552.20887.qmail@eos.oasis-open.org> <4AD2AB4C.5050102@sun.com">4AD2AB4C.5050102@sun.com> <4AD2AB4C.5050102@sun.com">mailto: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?

Best,

Kris
Sowmya Kannan wrote:

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:-).
 
Thanks
Sowmya
 
 
 
 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
conref_push.doc.
 
Document Description:
 
 
View Document Details:
 http://www.oasis-open.org/committees/document.php?document_id=34627
 
Download Document:  http://www.oasis-open.org/committees/download.php/34627/conref_push_2.doc
 
Revision:
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
  

 

--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail.  Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php