RE: [dita-adoption] Reminder - Please review Keyref feature overview

["Su-Laine Yeo" <su-laine.yeo@justsystems.com>]

Hi Sowmya,

You've done an incredibly thorough job on this and it's been very useful
for me in getting my head around keyref. Here are my comments so far:

1) I think there is an important typo in the "Creating Links from Terms
and Keywords" section: You currently have:

seabirds.dita 
<concept id="seabirds" xml:lang="en-us">
    <title>Sea Birds' Diet</title>

This should be:

seabirdsdiet.dita 
<concept id="seabirdsdiet" xml:lang="en-us">
    <title>Sea Birds' Diet</title> 

2) In the "Creating Links from Terms and Keywords" section, specify the
behaviour of links in print output. I.e. does it have no effect, does it
append "on page x" or is it left undefined?


3) In the "Swapping out Variable content:" section, I suggest a
rewording for clarity:

Change:

"In a ditamap, keys may be defined for frequently changing content such
as UI labels, product name, version etc. Such keys may be defined using
a pointer (href) to another topic (as we will see in the conkeyref
example) or directly as labels in a ditamap. Labels may be redefined in
a different map and all relevant topics will automatically pick up the
new values." 

to:

"You can use the keys attribute and the <keyword> element as "variables"
for small pieces of content that change frequently, such as UI labels,
product names, and version numbers. For example, you can put a
particular product name into a DITA map, and indicate in topics where
you want the product name to appear. When you generate output using the
map, its topics will display the product name in the appropriate
appropriate places. For longer pieces of content that do not fit into
the <keyword> element, use the conkeyref feature instead. "

4) In the "Swapping out Variable content:" example, I suggest using
"prodname" and "version" as the keys rather than "prodnameYBF" and
"prodnameYBFver". Currently the example speaks to a use case in which
the user is delivering documentation for one version of one product but
doesn't know yet exactly how these strings will be spelled. This use
case can be handled pretty well using conref. Where keyref really shines
is when you want to deliver documentation for different products, which
you can do by creating a different DITA map for each one.

5) In the " A New Approach to Conditional Processing (profiling) using
Keys and Conkeyref:" section:  I like the example and I agree that in
this example, keyref has some great advantages over using @product.

I think it would be much more clear to represent conkeyref as being a
new practice, separate from "conditional text" which is based on
filtering by @product, @audience, @platform, or @otherprops. The
practice of "conditional text" has always referred to putting multiple
variations of content into a single file and filtering out some of the
variations. I think we should stick to this definition. The practice of
using @product,@audience, @platform, etc. in DITA 1.0 and DITA 1.1 is
what we have been calling "conditional text" all along, and the practice
will continue to be extremely useful in DITA 1.2.

I suggest refactoring the section as follows:
- Change the title " A New Approach to Conditional Processing
(profiling) using Keys and Conkeyref:" to "Producing Customized
Documentation using Keys and Conkeyref:"
- State positively in the introductory sentences for the section what
the purpose is. E.g. "if you need to produce many variations of a
document which have roughly the same structure but have some variations
in content, you can use conkeyref to store your content using a separate
set of files for each variation."
- Change the title " DITA 1.2 Approach to Conditional Processing:" to
"Example Using Keys and Conkeyref:" and put this section first.
- Change the title " DITA 1.1 Approach to Conditional Processing:" to
"Same Example Using Conditional Text:" and put this section below
"Example Using Keys and Conkeyref:"

6) As a heads-up, we are currently having a discussion on the DITA TC
mailing list regarding a possible new attribute:
http://lists.oasis-open.org/archives/dita/200902/msg00024.html . If the
TC accepts the proposal, you should use localdisplay="no" instead of
toc="no" in all examples. If the TC doesn't accept the proposal, you
will probably need to make much more radical changes for your examples
to work.

7) The first sentence of each section should use active voice to
summarize describe what the user can do and how. I will try later to
send you some specific suggestions for rewording.

I really appreciate the amount of effort and attention to detail you've
put into this. You've set a high bar for the rest of us!

Best regards,
Su-Laine


Su-Laine Yeo
Interaction Design Specialist 

JustSystems Canada, Inc.
Office: 778-327-6356 
syeo@justsystems.com
http://na.justsystems.com 


-----Original Message-----
From: Sowmya.Kannan@Sun.COM [mailto:Sowmya.Kannan@Sun.COM] 
Sent: Monday, February 09, 2009 10:03 AM
To: dita-adoption@lists.oasis-open.org
Subject: [dita-adoption] Reminder - Please review Keyref feature
overview

Hi,
In our mtg last week, Gershon proposed that we review the Keyref feature

overview in our Adoption TC mtg on Feb 11 at 4pm GMT.

Please review the document when you get a chance.
http://www.oasis-open.org/committees/document.php?document_id=30387

Thanks
Sowmya

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