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: Public review over; summary of comments and changes since last TC meeting



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)





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