This Wiki page is designed to collect comments on the second review of the DITA 1.2 specification, 21 September - 3 October 2009. This review is being conducted by members of the OASIS DITA Technical Committee.
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 (3 comments in progress)
Paul [2009-09-22]: Currently says:
- DTDs and schemas
- The DTDs and schemas define DITA markup for the DITA vocabulary modules and concrete document types, as well as catalog files. While the DTDs and schemas should define the same DITA elements, the DTDs are normative if there is a discrepancy.
The word "schema" (especially lowercase) includes DTDs, XSDs, RelaxNG, and others. We should say XML Schemas (XSDs) here to indicate we are referring to W3C XML Schemas. Also, the "as well as catalog files" at the end of the first sentence doesn't work. Guessing what we are trying to say here, I suggest:
- Document Type Definitions (DTDs) and XML Schemas (XSDs)
- The DTDs and XSDs--along with catalog files--define DITA markup for the DITA vocabulary modules and concrete document types. While the DTDs and XSDs should describe the same DITA vocabulary, the DTDs are normative if there is a discrepancy.
[Eberlein, 2 December 2009] Done; thanks for the suggested rewording.
Paul [2009-09-22]: Re: Changes since DITA 1.0.
Why does this section look like changes from 1.0 to 1.1? Where are the changes from 1.1 to 1.2?
[Eberlein, 2 December 2009] I don't know, Paul. I distinctly remember writing such as section. In any case, I have added it back
Paul [2009-09-22]: Re: Authors, Reviewers, Members, Special Thanks. Per earlier email, I suggest:
- Preceding "Authors", we have a paragraph saying something like "this spec is a product of the DITA TC of OASIS."
- Instead of "Authors", call the following list "Editors".
- Delete completely both the "Reviewers" and "Members..." section.
- Delete the currently empty "Special Thanks".
[Eberlein, 2 December 2009] Done
Deferred to DITA 1.3
[Hamilton, 03 October 2009] It would be useful if references to the attributes and elements in the specification could link to their definitions, so that in appropriate formats (HTML, CHM, etc.) they would be live links. I suspect that can be done in the transform given the consistent @attribute and <element> syntax used throughout.
[Eberlein, 2 December 2009] I agree that the specification would benefit if we implemented a consistent linking strategy. However, I think a wholesale implementation of cross references would be overwhelming and contrary to DITA best practices for linking. I also regretfully think that there are limits to what we can accomplish in the DITA 1.2 time frame. Would you be interested in working on this for DITA 1.3? The issues that I think we should consider are:
- What is a useful number of cross references? How many is too much?
- Shall we implement a linking strategy using only relationship tables links, or do we permit links to be defined at the topic level? If the latter, what are reasonable and useful guidelines?
[JeffO, 05 October 2009] There is some "boilerplate" text from OASIS that was included as part of the DITA 1.0 and 1.1 specifications. Is the Overview section the place where that will be covered?
[Eberlein, 2 December 2009] Can you point me to this content? Thanks.
[JeffO, 05 October 2009] Is the title "Overview of the DIA 1.2 specification: Complete version" just for the review copy? If not, we need to explain what the "complete version" is and what other versions are available.
[Eberlein, 2 December 2009] I agree that we need this content. I'll post to the list and see if we get a volunteer for writing. I've personally been so ambivalent about the packaging decisions that I doubt I am the right person to write content about it.
[JeffO, 05 October 2009] It would be good to include a statement near the front that gives a date and clearly says what the status of the current version is (preliminary unapproved draft, approved committee draft, final OASIS standard).
[Eberlein, 2 December 2008] I added an additional row to the History table. It now contains the following text for our next review: 'This draft of the DITA 1.2 specification issued for an internal review by the OASIS DITA Technical Committee. This draft is a preliminary and unapproved."
[JeffO, 05 October 2009] The first paragraph could say a little more, perhaps:
- The Darwin Information Typing Architecture (DITA) 1.2 specification defines a set of document types for authoring and organizing topic-oriented information, procedures for processing the document types, and a set of mechanisms for customizing, combining, and extending document types using a process called specialization.
[Eberlein, 2 December 2009] I left the content of the <shortdesc> as is. Do we really want to state that we are providing "procedures for processing the document typle"? I don't think so ...
[JeffO, 05 October 2009] What is a "concrete document type"?
[Eberlein, 2 December 2009] Removed all references to a concrete document type.
[JeffO, 05 October 2009] In the Web TOC the Architectural Spec. comes before the Language Reference, but in the overview the Language Spec. comes before the Arch. Spec. It would be better if they appeared in the same order.
[Eberlein, 2 December 2009] Order changed.
[JeffO, 05 October 2009] In additon to the 3 sections listed for the Language Reference there is also sections on "Commonly Referenced Attributes" and "Conformance".
[Eberlein, 2 December 2009] I added the following sentence to the <dd> element for the Language Reference: "It also includes a section titled "Commonly referenced attributes" that applies to all three of the preceding sections. I also added a <dlentry> element for Conformance.
[JeffO, 05 October 2009] I think it would be better to rename the "Changes since DITA 1.0" to be something like "Changes included in DITA 1.1", add a new section "Changes included in DITA 1.2", and move both sections out of the overview and into an appendix.
[Eberlein, 2 December 2009] I agree with renaming the sections; I am not yet sure that we want to move material into appendixes -- I need to think about how that affects the build process for the three different packages.