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.
Kris