Next in thread →
Next in month →
Re: [dita] Public review over; summary of comments and changes since last TC meeting
Kristen and Robert,
Congratulations on all your work updating the spec in response to comments during the review, especially the marathon during the last two days in response to the massive amounts of content affected by Patrick and Jacques's review. When I saw their comments yesterday, I expected it to take at least through the weekend for them all to be dealt with.
You guys are amazing!
Regards,
Nancy
p.s. I do have one comment related to the hanging paragraphs/[sub]section
numbering issues. Those comments are a result of the TC taking a
position firmly on one side of what we might call a tech content
disagreement/divide about how to modularize content. I've had multiple
clients who required that sections show up in the TOC, with and
without numbers; a cursory review of the dita-users list will show that
many other implementers have had the same requirements. When our
position leads to careful readers being confused, maybe we (or the
adoption TC?) should consider documenting the issue, with guidelines for
following the TC recommendations without creating confusion and/or
perceived inconsistency. Obviously this isn't part of 1.3, but I'm not
sure that just sweeping those comments away under the rubric of 'best
practices' is fair to users of content produced using DITA..
_____________
Nancy Harrison
Infobridge Solutions
On Sat, Aug 8, 2015 at 9:36 AM, Kristen James Eberlein <> wrote:
Attention voting TC members:
The public review ended yesterday; Robert and I as spec editors
want to give you a summary of the new comments and our responses
to them.
Over 6-8 August, we received the following new comments:
Patrick Durusau: 21
Jacques Durand: 13
Patrick Durusau and Jacques Durand are members of the OASIS
Technical Advisory Board (TAB), which is now trying to provide
comments during the first 30-day review for each specification
draft. (Although they are members of the TAB, we treat their
comments just as we do comments from anyone else.)
As usual, we read, contemplated, and handled their comments
with the same guiding principles that we have, as a TC,
articulated and refined during the DITA 1.3 process:
A strong commitment to technical accuracy but also ease of
reading, especially for readers for whom English is a second
language.
An understanding that our work product, although a technical
specification, contains tutorial information and best
practices.
A strong commitment to backward compatibility, with the
implication that we cannot make any changes in DITA 1.3 that
would invalidate or break any existing DITA implementation.
An eye to our schedule and roadmap, being mindful that the
DITA community is eager for DITA 1.3.
The new comments and our resolutions for them can be grouped as
listed in the following table. We urge you at read the draft
comment log at
https://www.oasis-open.org/apps/org/workgroup/dita/download.php/56253,
before the TC is asked to approve it at our next meeting, but we
wanted to provide a summary also.
Category
Comment
Number of comments
Editor's response and explanation
Additional information
Future TC work items or
commentary
References
Normative and non-normative references and
how they are cited
8
Accepted
We struggled to discern clearly how OASIS
defined "normative" versus "non-normative information.
Editors had conference calls with Eliot Kimber and Chet
Ensign.
Document how OASIS understands these
references and wants them used in specifications.
Precedence of spec artifacts
Written spec cannot be authoritative if
there is a conflict with grammar files
1
Accepted
This is simply a basic OASIS rule.
Ensure that DITA TC is clearly aware of
this change.
Normative and non-normative wording
Usage of the normative term MUST versus the
non-normative must
2
Accepted partially
Asked for us to review every instance of
"must" and "must not" (287). We did so, and confirmed that
no usages should be normative. In some (but not all)
causes, we made wording changes if they improved clarity
or we could remove the word "must" in order to prevent any
possible reader confusion about whether the usage was
intended to be normative.
Further review the
"Keyword Guidelines for OASIS Specifications and
Standards".
Further review the Global English Style Guide: Writing
Clear, Translatable Documentation for a Global Market.
Document our practices and their rationale.
Document ways that we very properly use these terms,
especially when discussing best practices for authors and
practitioners, in examples, and so forth.
Document ways to recast sentences when authors' first
reaction might be to use "must", "should", or "may", they
could recast the sentence.
For DITA 2.0, carefully review legacy Language Reference
topics. Consider whether we want to make normative
statements about rendering, or whether an non-normative
appendix that listed rendering expectations in a single
place would be more useful.
Usage of the normative term SHOULD versus
the non-normative should
2
Accepted partially
Asked for us to review every instance of
"should" and "should not" (463). We did so, and confirmed
that no usages should be normative. In some (but not all)
causes, we made wording changes if they improved clarity
or we could remove the word "should" in order to prevent
any possible reader confusion about whether the usage was
intended to be normative.
Reviewed a few instances of "should" with Chet Ensign to
ensure our working practices were on-board.
Usage of the normative term MAY versus the
non-normative may
1
Accepted partially
Asked for us to review every instance of
"may" and "may not" (401). We did so, and confirmed that
no usages should be normative. In almost all causes, we
substituted the words "might" or "can".
Usage of might, need, and can
4
Rejected
We did not examine every instance of these
words, as well we had a very good sense of how they were
used after reviewing every instance of
must, should, and may. (We did remove two instances of
"might choose".)
Wording tweaks
Meaning of "all OASIS-approved
specification"
1
Rejected
This was in regard to text concerning the
editions, which was TC approved after much work.
Style points
Section numbering
2
Rejected
DITA TC does not number sections or chunk
sections into separate topics at rendering time. All of
our sections do have @id attributes so that they can be
easily referenced, either in DITA source or XHTML output.
Document our practices and their rationale.
Capitalization of titles
1
Rejected
The DITA TC uses the IBM Style Guide
as our authoritative reference.
"Hanging paragraphs"
1
Rejected
This is our practice of having text in
parent topics. (Jacques Durand suggested having empty
parent topics, and then including any text in an
introductory topic.)
Document our practices and their rationale.
Occasional lists that are not organized
alphabetically
1
Deferred
For all 1.3 content, lists are sorted
alphabetically. All the quick reference lists are sorted
alphabetically. Legacy lists are not.
Discuss and develop policy on this. If
policy calls for it, modify source for DITA 2.0.
Usability
Lack of cross references
1
Deferred
Make mentions of all elements, attributes,
and attribute values hyperlinks to their definitions in
the Language Reference topics.
Discuss and develop policy before
information architecture for DITA 2.0 is designed. (TC
members have not agreed on this previously; some like the
idea; others are concerned that such as massive addition
of links would impede readability and increase processing
time massively.)
Conformance
Conformance requirement for the wrong
conformance target
1
Accepted partially
Reviewer misinterpreted the statement; we
revised to improve clarity.
Inadequate definition of conformance
targets
2
Deferred
Our response:
"We'll work on this when we redo the conformance topic for
DITA 2.0 (the next expected release). We feel that we are
limited in what we can change in 1.3 based on the content
that existed before, the previous conformance clause that
was generally even less explicit, and our commitment to
backwards compatibility with 1.2.
Personally we'd like to start the 2.0 process with a focus
on conformance items, and let the DITA 2.0 content flow
from that."
Review "Guidelines
to Writing Conformance Clauses" (draft document by the
OASIS Technical Advisory Board).
Review these comments in detail as we begin work on DITA
2.0.
Take Patrick Durusau up on his offer to conduct a workshop
for spec editors and TC members.
Consider starting the DITA 2.0 process with a focus on
conformance.
Conformance topic duplicated in editions
1
Deferred
Conformance topic should contain precise
references to normative statements
1
Deferred
Conformance language is weak and vague at
times
1
Deferred
Blanket statement in conformance section is
too open-ended, conflicting with follow-up
1
Deferred
When there are conformance options, the
Conformance topic should summarize these and make it clear
a conformance claim should include them
1
Deferred
Conformance should require validity against
DTD/Schema
1
Rejected
Current language is intentional and
technically precise.
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
---------------------------------------------------------------------
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
Next in thread →
Next in month →