This is a very cool example! The article would really benefit from the
addition of these scenarios.
Thanks
Sowmya
Kristen James Eberlein wrote:
4AD3DD4A.9050004@pobox.com" type="cite">Forwarding on behalf of Stan Doherty. Many thanks,
Stan! This is a great example.
Kris
-------- Original Message --------
Hi
--
I
can't post directly to the Adoption email list .. .so here's an FYI for
you.
I
am actually using conref push at my company to supplement
software-generated DITA topics with content written by human beings
like me.
Here's
the process:
1.
Each night, the software build scripts in my engineering group
generate hundreds of DITA reference topics about our software
APIs.
2.
Any content that I add to these generated topics gets overwritten
the next night. Doah!
3.
With DITA 1.2, I now "push" content into generated topics from
my conref push libraries by referencing persistent IDs in the
generated topics.
My
"value add" writing persists between builds of the generated topics.
When you did not or can not generate base DITA content, conref
push provides you some options. Kind of after-the-fact authoring.
Pax,
Stan
Doherty
-----Original Message-----
From: "Joann Hackos" [joann.hackos@comtech-serv.com]
Date: 10/12/2009 04:48 PM
To: "Kristen Eberlein" <KEBERLEIN@POBOX.COM>, "DITA Adoption
TC"
Subject: 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"
target="_blank">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"
target="_blank">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
---------------------------------------------------------------------
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
|