OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[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).



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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]