dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Re: [dita] Feedback from Mary McRae
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: Eliot Kimber <ekimber@reallysi.com>
- Date: Fri, 28 May 2010 17:38:29 -0400
Hi Eliot,
I also agree with Bruce, but to different
ends :-) That is, in the case of child link summaries, they exemplify a
DITA best practice, and the DITA spec should practice what it preaches.
We could, of course, simply eliminate
all overviews and introductory material. Those types of material are inherently
redundant. But I can't imagine that's the intent of Mary's feedback. Intros
and overviews make the world go round, and make specs easier to absorb.
It is a useful and obvious redundancy.
Our use of child-link summaries allows
automation of this redundancy, which makes it even more obvious, more consistent,
and less error-prone. I don't think we should be penalized for doing a
DITA-like job of handling intro material.
Michael Priestley, Senior Technical
Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
From:
| Eliot Kimber <ekimber@reallysi.com>
|
To:
| "Bruce Nevin (bnevin)" <bnevin@cisco.com>,
dita <dita@lists.oasis-open.org>
|
Date:
| 05/28/2010 05:07 PM
|
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
---------------------------------------------------------------------
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]