This Wiki page is designed to collect comments on the third review of the DITA 1.2 specification, 11 December 2009 - 4 January 2010. This review is being conducted by members of the OASIS DITA Technical Committee, OASIS DITA Adoption Committee, and the OASIS Technical Advisory Board.

Contents

Overview of the DITA 1.2 specification

Important: Reviewers, be sure to preface comments with your name and the date, for example: [Eberlein, 18 September 2009]

Overview of the DITA 1.2 specification

Completed

Paul [2009-12-11]: Minor, but in the History table near the end:

This draft is a preliminary and unapproved.

Delete "a".

[Eberlein, 11 December 2009] Done

Completed

[MPriestley, 17 December 2009] Appendices of non-normative material: don't need to say non-normative, implies that everything else is normative

Paul [2009-12-21]: Appendices are usually assumed to be informative (non-normative), and I've made comments for the conformance section to say explicitly that Appendices are informative (non-normative) unless explicitly said otherwise. As long as we do that, I agree with Michael that we don't need to say non-normative here.

[Jeff, 2 Jan 2010]: Not sure I agree with MP and Paul, but I can live with that approach as long as it is made clear that the appendices are non-normative somewhere, probably at the start of each appendix. I'm not sure saying this in just the conformance section does that, however.

[Eberlein, 8 February 2010] Changed heading to simply read "Appendices"

Completed

Paul [2009-12-21]: Given the Appendix about changes to the spec, I think the two "Changes" sections (which aren't complete anyway) should be deleted from this Overview topic.

[Jeff, 2 Jan 2010]: I agree, but some of his information was an official part of DITA 1.1 spec. and there is no appendix listing the changes between 1.0 and 1.1, so we should move this information into the appendix if we delete it from here.

[Eberlein, 8 February 2010] Commented out the material in this topic (dita-1.2_complete_overview.dita). Added an anchor for this comment, and added a comment to the Wiki page for Appendices, indicating that the material should be covered there.

Completed

[MPriestley, 17 December 2009] Under "Editors": Should we also include people who contributed feature designs or implementations? Note this is currently not mentioning me (keyref, the conref enhancements, etc.), Erik Hennum (taxo/classification), or Eric Sirois (schema implementation)

[RDAnderson, 17 December 2009] Will let the group decide on the others, but I think Eric should be added - he's done a large amount of work editing the Schemas.

Paul [2009-12-21]: I tend to prefer to list as editors a small number of people who were key in producing the final spec with the assumption that the entire TC contributed, but you don't list everyone. But as long as I'm not listed, I don't really care.

By the way, Eliot Kimber has no double letters in his first name.

[Eberlein, 9 January 2010] For the first draft, I modeled the acknowledgments on what appeared in the 1.1 spec. In the 2nd review, Paul Grosso objected rather strenuously to that approach. Here's an official directive from OASIS:

"A specification that is approved by the TC at any level must include a list of people who participated in the development of the specification. This list shall be initially compiled by the Chair, and any Member of the TC may add or remove their names from the list by request."

I read the above verbiage as suggesting that we should acknowledge the following groups of people:

Authors of feature proposals
Individuals who write sections of the spec
Individuals who review the spec
Individuals who implemented the DTDs and XSDs

Am I missing any categories?

[Eberlein, 16 February 2010] We discussed this at today's TC meeting and agreed that the above categories of people should be mentioned. Performed the following actions:

Removed content from overview topic
Built a DITA topic for "Acknowledgments" (r-acknowledgments.dita) that will be located in an appendix, per the OASIS model discussed at http://docs.oasis-open.org/templates/OASISSpecificationTemplateGuidelinesV4.0.html#AA
Added comment to the Wiki page for appendices (see http://wiki.oasis-open.org/dita/Appendices3#Acknowledgments)

Completed

[Jeff, 2 Jan 2010]

I think it would be good to add some new information after the first paragraph that might read something like this:

The DITA 1.2 specification adds a number of new features, capabilities, and document types to DITA, including indirect addressing via map-defined keys; the ability to define per-element-type content model constraints in DITA document types; a new general task document type; extended markup for glossaries and terminology; specializations for learning and training, for machine industry, taxonomy, ontology, and controlled vocabulary content. See the appendix "Changes from DITA 1.1 to 1.2" for a complete list.
DITA 1.2 is compatible with previous versions of the DITA specification in that all valid DITA 1.0 and 1.1 documents remain valid under DITA 1.2. However, some changes to existing document type shells and specializations may be required in order to maintain the same behavior in DITA 1.2 as was available in DITA 1.0 and 1.1. See the appendix "DITA 1.1 to 1.2 Migration Guide" for additional information.

[Eberlein, 28 February 2010] Let's wait and see how the Appendices develop. This might better belong in the description of the appendices.

[Eberlein, 5 March 2010] Moved above discussion into a draft comment in the file; changed disposition to "Completed."

Completed

[Jeff, 2 Jan 2010]

Elsewhere (comments on the TOC and overall content) I've suggested reordering, changing nesting levels, and changing titles within the Arch Spec. section. If those changes are adopted, then some updates will be required here. Even if those changes aren't adopted, the current description doesn't not really match the current TOC for the Arch Spec. since it needs to include the "Configuration and extension section" or perhaps the "Specialization" and "Configuration and extension" sections could be included under a new higher level "Specialization and customization" section.

[Eberlein, 28 February 2001] Updated to match the current TOC.

Completed

[Jeff, 2 Jan 2010]

The statement "This document contains the following parts:" is left over from the 1.1 spec. and while not incorrect, doesn't include all of the sections in the architectural spec.

[Eberlein, 28 February 2001] Updated to match the current TOC.

Completed

[Jeff, 2 Jan 2010] It would be good to give more visibility to the "Base", "technical content", and "learning and training" sections. They should be as least as visible as the four sections in the bulleted list. It would be good to list the document types that are part of the Technical Content and Learning and Training families to give folks a better idea of what is included where. If there are any other document types that aren't part of these two families, we should indicate where they are described as well.

[Eberlein, 28 February 2010] I agree, but I'm not sure that this overview is the correct place for it.

[Eberlein, 5 March 2010]: Added Jeff's comment (slightly edited) to a draft comment in the DITA topic. (Jeff also is working on a such a description.) Changed disposition of comment to "Completed."

Completed

I'd move the paragraph that starts "While the architectural specification ..." up to be the third paragraph and I'd have it apply to the entire specification and not just the arch. spec.

[Eberlein, 28 February 2001] Done

No work required

[SDoherty, 8 Jan 2010]

Some statement about the "new" or "refocused" audience for the spec needs to be included before the Introduction. This doesn't need to be extensive, but it should make clear that vendors, architects, and XML programmers are the focus. I can dig out emails and/or notes from meetings in which we discussed this refocused audience.

[Eberlein, 28 February 2010] This overview already contains the following paragraph:

"While the DITA 1.2 documentation does contain some introductory information, it is intended neither as an introduction to DITA nor as a users guide. The intended audience of this documentation consists of implementers of the DITA standard, including tool developers and XML architects who develop specializations."

Rejected

[SDoherty, 8 Jan 2010]

Along the same lines, a <section> on the different roles and responsibilities of the DITA TC and the DITA Adoption TC would be useful.

[Eberlein, 16 February 2010] I'm sympathetic to the impulse, but I think this is be non-normative material that should be handled someplace other than the DITA specification.