I've completed my review of the 1st arch spec draft through the DITA
processing section (I didn't bother reviewing the specialization section
since I edited it). My comments are in the review wiki.
My main concerns with the 1st draft are:
- The discussion of IDs and references (addressing) needs to be reorganized
and refactored to be clearer. See my detailed comments. I would like to help
with that refactoring, if not take it on entirely. In general, I think need
to more clearly separate the semantics of relationships (e.g., content
reference) from the details of how those relationships are established
(conref/conkeyref), both to make the discussion clearer and to make it
easier to apply new addressing mechanisms to existing relationship types in
the future.
- We need to come to consensus on inheritance vs. cascading vs.
propagation/imposition. I think the discussion needs to more clearly
separate what happens within maps and what happens between maps and
referenced topics, because the two are completely distinct operations and
have different implications.
- The need to rationalize the architectural discussion of syntax details
with the Language Reference discussion of the same details remains.
Cheers,
Eliot
----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email: ekimber@reallysi.com