dita — archive

[Eliot Kimber]

I agree generally with Bruce: we're producing a spec that happens to be authored using DITA markup, not a technical document authored and delivered using modular tech doc best practices. In particular, the requirements and practices of standards are necessarily different from those of technical documentation generally. In particular, redundancy must be avoided and every clause needs to have a clear and persistent identifier in all renditions. Even though we, as the authors, know the shortdesc-generated links are always identical to the shortdesc as presented in the linked topics, readers cannot know that, thus the perception of redundancy. Likewise any place that conref has been used to reflect the same content in two locations. In the work I did for the FASB, where we were documenting a standard, we used a special element to capture the clause numbers, rather than relying on automatic numbering. This type of approach may be required for the DITA spec, at least for the Arch Spec (the lang ref has natural identifiers since each tag name must be globally unique). Cheers, Eliot On 5/28/10 9:42 AM, "Bruce Nevin (bnevin)"