|Kristen James Eberlein||May 28, 2010 7:03 am|
|Bruce Nevin (bnevin)||May 28, 2010 7:41 am|
|Robert D Anderson||May 28, 2010 7:57 am|
|Don Day||May 28, 2010 8:01 am|
|Kristen James Eberlein||May 28, 2010 10:16 am|
|Eliot Kimber||May 28, 2010 2:05 pm|
|Michael Priestley||May 28, 2010 2:37 pm|
|Grosso, Paul||Jun 9, 2010 8:21 am|
|Subject:||Re: [dita] Feedback from Mary McRae|
|From:||Eliot Kimber (ekim...@reallysi.com)|
|Date:||May 28, 2010 2:05:28 pm|
I agree generally with Bruce: we're producing a spec that happens to be authored using DITA markup, not a technical document authored and delivered using modular tech doc best practices.
In particular, the requirements and practices of standards are necessarily different from those of technical documentation generally. In particular, redundancy must be avoided and every clause needs to have a clear and persistent identifier in all renditions.
Even though we, as the authors, know the shortdesc-generated links are always identical to the shortdesc as presented in the linked topics, readers cannot know that, thus the perception of redundancy. Likewise any place that conref has been used to reflect the same content in two locations.
In the work I did for the FASB, where we were documenting a standard, we used a special element to capture the clause numbers, rather than relying on automatic numbering. This type of approach may be required for the DITA spec, at least for the Arch Spec (the lang ref has natural identifiers since each tag name must be globally unique).
On 5/28/10 9:42 AM, "Bruce Nevin (bnevin)" <bne...@cisco.com> wrote:
departures from how we've done things previously and arguably counter-intuitive to DITA principles.
Insofar as it conflicts with 'DITA principles', the counter to this is that this spec should exemplify what it specifies and the recommendations of the Adoption TC. This is obviously not true of all OASIS standards, but clearly appropriate for a standard that is effective on documentation and is applied to the documentation of the standard itself. It is that recursive self-application that should exempt DITA from some across-the-board generalizations. Fortunately, we're not bedevilled with small minds in OASIS, so we should be able to avoid a foolish consistency <http://www.bartleby.com/100/420.47.html> . (That said, it applies equally to clinging to "how we've done things previously" without such warrant.)
From: Kristen James Eberlein [mailto:kr...@eberleinconsulting.com] Sent: Friday, May 28, 2010 10:04 AM To: DITA TC Subject: [dita] Feedback from Mary McRae
Hi, fellow TC members.
We got feedback from Mary McRae about the draft of the DITA 1.2 spec yesterday. I've added Mary's comments to a Wiki page, to make them easier to read -- and to make it easier for us to track our progress in fixing issues:
If you browse through the page, you'll see that we are left with four main areas of work or negotiation:
* Need for a namespace document * (PDF) Stylistic improvements, to better align it with OASIS templates (footers, styles for various levels of titles) * (PDF) Need to fix text overruns in tables * (XHTML) Mary has requested changes from how the DITA 1.0 and DITA 1.1 specs were issued:
* Number all topics with section and subsection numbers * * Remove link previews generated from <shortdesc> elements, to remove duplication * Ensure that all topics contain a link to the "Next" topic in the reading order
I've requested feedback from Mary about which issues need to addressed before we can issue the spec for public review. I sincerely hope that she will permit us to finish refining our PDF styling during the public review. However, the first and second changes requested to the XHTML output call for more serious reflection, as they are departures from how we've done things previously and arguably counter-intuitive to DITA principles.
Thoughts from other TC members?
The third XHTML item either already is effectively handled -- the URL at the bottom of each topic takes the reader back to the appropriate bookmark for the topic in the TOC -- or could be addressed by an override that IBM uses for their tutorial specialization.
Kristen James Eberlein Principal consultant, Eberlein Consulting Secretary, OASIS DITA Technical Committee Charter member, OASIS DITA Adoption Committee www.eberleinconsulting.com <http://www.eberleinconsulting.com/> +1 919 682-2290; keberlein (skype)
-- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.reallysi.com www.rsuitecms.com
--------------------------------------------------------------------- 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