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: What should be in the architectural specification?

I am struggling to develop a solid sense of what should be in the architectural specification. While the 1.1 architectural specification provides a fairly clear statement of what the document is NOT, it doesn't really nail down what the document SHOULD provide:

"While the specification does contain some introductory information, it is not intended as an introduction to DITA nor as a users guide. The intended audience of this specification consists of  implementers of the DITA standard, including tool developers and specializers."

Just to throw out a few observations:

The architectural spec is very uneven in its coverage. It contains, for example:
  • Detailed information about the basic structure of a topic but slim corresponding information about the basic structure of a map.
  • Fairly detailed information about attributes used at the map level-- but no information about attributes used at the topic level.
  • Not one but two basic examples of a relationship table and how links are generated in output. (The language spec covers the same material with another yet entirely different example.)
A bigger question is how do we decide what should be handled in the language specification and what should be discussed in the architectural specification? Right now, discussion of keyref -- which I think must be covered in the architectural spec -- is covered in the language spec in a collection of topics located in "Commonly referenced attributes" > "Complex attribute definitions" > "Using keys and keyref."

Does this material -- perhaps reworked some -- belong in both documents? If so, do we reuse identical content in both contexts?

Also, where does the bulk of keyref coverage belong? Per Gershon's spreadsheet, it is slated to be included in the processing topics (id.dita), but I think we also need to cover this in the map topics. Nancy, maybe you and I can discuss this further offline ...

I'd be interested in hear people's thoughts about all, information about how the specification documents were originally planned and authored (and intended), and general discussion about this, especially from TC members who have been working on the architectural spec.


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