Rethinking the DITA Reference Docs

[Eliot Kimber <ekimber@reallysi.com>]

I've been thinking a good bit about the DITA reference docs lately, both 
in the context of the modularization we're planning for the spec itself 
as well as in the context of integrating the reference docs with the 
documentation for specializations.

The main challenge I ran into was that the docs as currently written use 
xrefs to link from the "contains" and "contained by" sections to the 
related element types.

This makes it essentially impossible to refactor the docs to reflect a 
subset of modules (e.g., specializations that only use the base 
highlight and indexing domains) or use in new specializations just by 
including the docs into your own map: you would have to copy and modify 
every entry. Definitely not realizing the promise of DITA to enable 
mix-and-match interchange.

I can think of two possible solutions:

1. Use metadata attributes on each xref to bind references to modules.

2. Replace the explicit lists of element types with either references to 
  more generic placeholders (e.g., "ph and its specializations" or 
"paragraph content") or only to base types, with the explicit 
implication that the base types may be extended on a per-shell basis by 
specific modules.

3. Use relationship tables to link types to their containers and contents.

The first option would work and would make things configurable. It would 
be relatively easy to either update the existing source with search and 
replace or update the code that generates those bits to include the 
defining module.

The second option would require an awful lot of rewriting and would 
probably be unsatisfying in the end.

The third option is more complete but would require either custom coding 
to implement processing the reltables to synthesize the contains and 
contained-by sections or refinement of the Toolkit to make display of 
reltable links more flexible than it is today (that is, be able to get 
something other than "Related reference" as the header for a set of 
generated related links).

The third option would also allow for props= attributes that take the 
names of the different modules to enable run-time inclusion or exclusion 
of links for specific modules, making it easy to tailor a master 
all-inclusive map.

There's no difficulty in generating the reltables themselves--there's 
plenty of tooling that can process the declarations as XML, so I'm not 
worried about that.

I'm not sure who is currently responsible for managing the DITA 
reference source, I suppose this most affects them in the short term. 
I'm willing to do what I can to code the required processing, either for 
generation of source data or rendering into HTML and/or PDF as my time 
allows. Since I would like a general solution for my client work I've 
got a bit of motivation to help find a better solution than the current 
source provides.

Cheers,

Eliot
-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770
www.reallysi.com
www.rsuitecms.com