We’ve responded to and assigned dispositions for each of the comments in the review. There are a number that we need to talk about at the TC level, so be sure and look at the “Referred comments” section below. Attached is a PDF of the review
content + draft comments entered in Content Fusion, as well as a PDF of the “Configuration” material that is currently in GitHub, with the content changed as a result of the review highlighted in
red.
Participants
TC voting members + volunteers
|
Participation in review P
|
Reviewed content as part of the stage three proposal #15
|
Dawn Stevens
|
X
|
|
Kris Eberlein
|
X
|
X
|
Stan Doherty
|
X
|
|
Nancy Harrison
|
|
|
Eric Sirois
|
X
|
|
Robert Anderson
|
X
|
X
|
Gershon Joseph
|
X
|
|
Carsten Brennecke
|
|
|
Eliot Kimber
|
X
|
X
|
Scott Hudson
|
X
|
|
Zoe Lawson
|
X
|
|
Bill Burns
|
X
|
|
Frank Wegmann
|
|
|
Comment dispositions
All comments in the review have been assigned a disposition:
- Accepted: Yes, we want to do this, but we cannot make the changes right now. There might be a dependency, or we might need to figure out where content should be placed.
- Closed: We do not need to make any changes to the source. Usually a reviewer has asked a question and someone has answered it.
- Completed: A reviewer has requested changes, and the work has been done.
- Deferred: A reviewer has requested changes, we agree that they would be ideal, but it’s low priority and unlikely to be done.
- Referred: We want the TC to talk about this. It might be a point that reviewers disagree about, or it might just be something that we think all TC members need to understand.
- Rejected: A reviewer has requested changes, but they are not going to happen. The requested changes might violate style guidelines, contravene decisions that the TC has already
made, or be something that the spec editors strongly disagree with.
Referred comments
These are important! We will discuss them at the next TC meeting.
Topic
|
Content that the TC needs to discuss
|
Disposition
|
1 Configuration, specialization, generalization, constraints, and expansion
|
Three comments about the chapter title
|
Referred
|
1.2.1 Overview of document-type shells
|
- One comment about the distinction between validation and grammar-aware processing
- One comment about moving material about “custom document-type shells are a best practice” to an appendix
|
Referred
|
1.2.2 Rules for document-type shells
|
Sample URN needing changes, will ripple through all RNG catalog files
|
Referred
|
1.2.3 Equivalence of document-type shells
|
One comment about whether the topic is necessary
|
Referred
|
1.2.4 Conformance of document-type shells
|
One comment about whether the topic is necessary
|
Referred
|
1.3.3 Vocabulary modules
|
- One comment about whether some “best practices” material should be moved elsewhere
- One comment about when structural specializations become dependencies
|
Referred
|
1.3.4 Specialization rules for element types
|
- One comment about rules for content models of specialized element types
- One comment about expanding on the difference between specialization and expansion
|
Referred
|
1.3.8 Specializing to include non-DITA content
|
Do we need to define “foreign content”?
|
Referred
|
1.4.2 Constraint rules
|
One comment about whether this topic needs to include information about the need to aggregate constraint and expansion modules if they are overriding the same vocabulary module
|
Referred
|
Accepted comments
Topic
|
Work to be done
|
Disposition
|
1.1 Overview of DITA extension facilities
|
Add link to generalization content
|
Accepted
|
1.2.1 Overview of document-type shells
|
Eliot to update graphic
|
Accepted
|
1.3.1 Overview of specialization
|
Zoe: Question about “unexpected consequences” of specialization
|
Accepted
|
1.3.1 Overview of specialization
|
Need to make sure that the expansion topics make it clear that a specialization is required. It might be a new specialization, or it might be an existing one, such as an OASIS attribute specialization not in use.
|
Accepted
|
1.3.6 @ class attribute rules and syntax
|
Need to include the example when we review the generalization content
|
Accepted
|
1.4.2 Constraint rules
|
Make reused content a conref
|
Accepted
|
1.4.5.1 Example: Redefine the content model for the <topic> element using RNG
|
Ensure that combine=”interleave” is covered where needed
|
Accepted
|
1.5.1 Overview of expansion modules
|
Recast some wording
|
Accepted
|
1.5.2 Expansion module rules
|
Need to add link after we have reintegrated content about generalization
|
Accepted
|
We track these comments – and the work done on them on a
Wiki page.
Deferred comments
Topic
|
Content
|
Note
|
1.4.4.2 Example: Constrain attributes for the <section> element using DTD
|
Rework example topics as task topics / write in 2nd person
|
Deferred
|
.5.3.4 Example: Aggregating constraint and expansion modules using DTDs
|
Show code for aggregating the constraint and expansion modules
|
Deferred
|
We track these comments – and the work done on them on a
Wiki page.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com
Skype: kriseberlein; voice: +1 (919) 622-1501