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