FW: Comments on DITA-like systems

["France Baril" <France.Baril@ixiasoft.com>]

Sandy allowed me to forward her comments on DITA-like systems so the
committee can address issues she met working with such systems.

Thanks for your input Sandy!

France Baril
Documentation architect/Architecte documentaire
I X I A S O F T

+1 514 279-4942
france.baril@ixiasoft.com
[   www.ixiasoft.com   ]

------------------------------------------------------------------------
---

I'm pleased that DITA is gaining wider acceptance, particularly from 
the likes of Arbortext, as it's an information architecture that I've 
found helpful in the past.

The company I last worked for originally had a LaTeX-based 
documentation system, in which any substantial piece of common material 
was separated out into another file for inclusion at points of use. 
There was no real overriding principle in the organisation of reused 
components.

Around three years ago (I think), I began a process of moving 
documentation to a DITA-like system - still using LaTeX rather than 
XML, but with a view to making it relatively easy to move to XML DITA 
at a later date. The new documentation that we produced using this 
topic-oriented system worked effectively and was easier to maintain. 
(I'm currently doing a contract with the same company and they're still 
using the system; most of the customer-facing documentation has now 
made the transition.)

The difficulties we had were probably not specifically related to DITA:

* We stored topic files in a directory hierarchy where the containing 
directory was meant to represent the context for the topic. However, it 
wasn't always easy to categorise topics in this way. Context actually 
has many facets (where you are in the software, what kind of user you 
are etc.), so it doesn't neatly map to a tree structure. Perhaps a 
topic database with multiple context attributes would be better. (DITA 
doesn't - or at least didn't - mandate any kind of structure above the 
topic level, for documents or for content storage.)

* Indexing requires greater discipline than for a standalone document, 
as each topic's index entries will appear in every document (print or 
online, user reference or installation guide) in which that topic is 
used. We had no means of controlling index entries at the document 
level, so it was hard to avoid similar index entries falling close 
together in some indexes while the same entries would be usefully 
separated in other indexes. One possible solution would be to 
over-index in the topic source files and then override a document's 
index using a per-document index-pruning file (but that's not something 
I've ever tried).

* Cross-references within a document can be difficult to single-source 
(this is definitely not an issue specific to DITA). In our system, we 
had two kinds of cross-reference: the first generated a topic name and 
page reference in print or a hyperlinked topic name in online help; the 
second, applied to a word or phrase in the topic, generated a trailing 
`(see ...)' reference in print or converted the word or phrase to a 
hyperlink in online help. The second kind of reference has the 
advantage that if the target topic is absent, the system silently 
ignores the cross-reference and the topic still reads well. (Of course, 
you might want the reference to point to different places in different 
documents, but that's another thing I haven't tried.) Sometimes we 
needed to use the first kind of reference, to avoid the awkwardness in 
print of mid-sentence parenthesised references. There must be better 
ways of handling cross-references for delivery in more than one medium.

I look forward to seeing how the DITA model develops under the auspices 
of OASIS.

Sandy Nicholson
Information Design Consultant
Ambertext