[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Feedback from Mary McRae
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). Cheers, Eliot On 5/28/10 9:42 AM, "Bruce Nevin (bnevin)" <bnevin@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.) > > /B > >> >> >> >> From: Kristen James Eberlein [mailto:kris@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: >> >> http://wiki.oasis-open.org/dita/CD01 >> >> 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. >> >> Best, >> >> Kris >> >> 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]