[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita-adoption] Reminder - Please review Keyref feature overview
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]