Questions generated as authors write the first draft

Use this page to keep track of questions that occur to you as you write the first draft.

Robert Anderson

Kris Eberlein

What should we do with contents of <draft-comment> elements from previous releases? Enclose them in comments? Add some conditional values? There is some valuable information in the older draft comments, but I want our working drafts -- when transformed -- to display only the 1.2-level comments.
How do we want to track revisions? We have two tasks at hand:
- Tracking revisions as we work on authoring the DITA 1.2 architectural spec (audience = authors, reviewers, and DITA TC)
- Marking significant new content for the finished version of the architectural spec (audience = readers of the DITA 1.2 architectural spec who want to know what has changed since DITA 1.1)
What rules do we use for unordered lists? Complete sentence as an introduction? Uppercase or lowercase for the list items?
Originally the master DITA map had collection-type=sequence set on many <topicref>elements. I've removed most of these, as they made no sense to me.
[16 June 2009] What do we want to do vis-a-vis noun strings? I have changed "base DITA document types" to "base-DITA document types."
[16 June 2009] The spreadsheet had the following information in the comment field for the "About the DITA 1.2 specification": "Need to consider where and how to document the info at this link: http://lists.oasis-open.org/archives/dita/200810/msg00009.html" Is this information adequately addressed in the arch spec? I don't think it belongs in this overview topic.
[16 June 2009] What format do we use for dates? Does OASIS mandate anything?
[16 June 2009] Here is the content of some DITA 1.1-level <draft-comment> elements that were in the "DITA map structure" topic. I have commented them out, but want to retain the substance so that we can determine whether they have been adequately addressed in the processing section of the arch spec:
- "Comment from Jeff Ogden 2007/01/22: Something that isn't spelled out anywhere that I know of, is when a topicref causes the topic content to be included in the output and when it doesn't. The TOC attribute will cause an item to be included in a TOC, but the content may be included even if there is no TOC entry. The print attribute can cause something to be omitted. What happens when the same topic is referenced more than once outside of a reltable? Are the rules the same for chunked outputs (Web, Help, ...) and for merged outputs (print/PDF, HTML File, ...)? What happens when the same topic is referenced more than once within a reltable? What happens when the same topic is referenced more than once in and outside of a reltable?"
- "MP response: I think what we need here is explicit process descriptions in the new process section: one for aggregation, and one for related link generation. I think out of scope for 1.1, but hopefully can be addressed in 1.2, and we can work on some drafts before then in any case."
[26 August 2009] What do we want to do about copyright information in the DITA source files? Right now this is very scattershot and different from one file to the next. For example, common/topic2.dita ("Basic topic elements" contains the following:
[26 August 2009] Where should <indexterm> elements go? In body of topic? In <prolog> of topic? In DITA map?

JoAnn Hackos

Nancy Harrison

Erik Hennum

A little concerned about the task orientation -- specifications are typically used to verify the result of implementation rather than as guidance for how to implement (because the implementation details will be specific to each vendor and because the vendor's innovation is in the implementation).

WEK: I agree with Erik. In editing his submissions, I realized that having "how to" topics is not appropriate for a specification: rules need to be defined declaratively. They can be supported by non-normative examples (the XSLT 2 spec is an excellent example of this approach), but the arch spec is not and should not be a tutorial. Of course, we should probably publish, through the DITA Adoption TC, a companion how-to document that can include all the tasks currently identified for the arch spec.

Gershon Joseph

How should we mark up or otherwise identify element names?
How should we mark up or otherwise identify attribute names? I've see @xyz, but not sure it's used consistently.
Some topics contain nested topics (one of mine is a concept that contains nested concepts). Should we move the child topics out into separate files?
How should we mark up attribute or element descriptions? I see (even in the same topic) some using <ul> and others using <dl>).

Eliot Kimber

10 June 2009: I have committed my first crude stab at the specialization section. I eliminated the procedural topics and replaced them with declarative design pattern rules or similar as appropriate (not completely written yet). I put a lot of effort into the introductory stuff. I moved all the specialization topics up under Specialization, removing the Specialization/Advanced Specialization split. I am liking the term "vocabulary module" as a general term to encompass structural and domain specializations and the general term "DITA vocabulary" to refer to all DITA-defined elements. The basic idea is that DITA defines an XML vocabulary, organized into modules, which can then be combined to form concrete document types. The specialization feature allows unilateral extension of the core vocabulary.
Topic "Processing Foreign Content" should, I think, be part of the lang ref entry for <foreign> since it's simply defining semantics for that element type, not defining a general architectural rule.
Topic "Data extensibility" should be integrated with the language reference entry for <data> since it is purely about the semantics and use of <data> and not about specialization in general.
Ditto "Generalizing data element specializations"
Per general discussion around moving how-to information out of the arch spec, I have created the subdirectory dita-implementation-how-to/ in SVN and moved there all the specialization-related topics that were how-to. I also created a top-level map for the publication. My intent is that this could be the start of or integrated with the proposed (and very necessary) "DITA Implementation Guide" that the Adoption TC should produce. You can take this as my volunteering to help with that effort, if not drive it.