Josef Pellizzari
- Challenges using DITA
Novartis built end of 2006 together with a vendor a small system
to demonstrate the concepts and benefits of component-based authoring
to internal business clients. For the demonstration a clinical study
report was used.
While DITA delivered to its promise to get going quickly we
encountered some challenges along the way:
- We could not really figure out what to do with nested topics.
There are two mechanisms of nesting topics: maps and
nesting directly. We could not find a way understandable for
users how the two mechanisms work together and we could
not find a way to integrate the two concepts on the UI
in an acceptable manner.
We "resolved" this by specializing topics and removing the
possibility to create directly nested sub-topics. This in
turn created a ridiculously fragmented document with 130
topics and made the user experience cumbersome in another way.
- Nesting of blocks
The DITA DTD is artfully crafted to avoid block-level
recursion.
At Novartis we had several times the need for deeper structures
then the one level offered by <section>. Examples are groups
of so-called "boxed warnings", which are themselves a sequence
of paragraphs.
From an earlier discussion with DITA specialist I understood
that something similar should exist in 1.2 - but I did not
yet check.
- Nice names all taken
We wanted to restrict the content model of DITA further. As a
general rule we want one way to achieve one thing, e.g. inside
list items there is no choice for inline or block content, it's
block, period. At least in the version (pre 1.1) we had the
impression that if we refine the content model of an element we
have to rename that element.
Unfortunately all the nice names (<p>, <li>, ...) are taken and
our consultant at the time proposed uppercase element names
or hideous constructions with underscores.
- Deep linking
Deep linking (href="xuz#uvw") has proven tricky. Mostly due to
missing tool support the referential consistency could be violated
by users.
There were some other implementation issues in OT which made
deep linking an adventure we tried to avoid.
- Duplicate inclusion
In at least one situation we included the same content twice
via conref. This created duplicate IDs and a mess when trying
to cross-ref the material.
Only sensible way out was to avoid cross-referencing material
imported via conref altogether.
- Bookmap structure
The structure with front matter etc. does not really match
our documents. We could squeeze all our information into
normal topics and used specialized sections to trigger
actions when published.
- Using Open Toolkit
Adapting the stylesheets of the OT to produce Novartis visual
identity and to follow our internal guidelines proved very
tedious and costly. We are tempted to create stylesheets
from scratch the next time.
- Conref
As conref introduces deep links into topics we tried to avoid
this as well. On the other hands tables and figures are typically
material produced elsewhere asynchrounously and just integrated
into the document. As there was no other construction to pull
content into the body of a topic we had to used, introducing
again deep links we wanted to avoid for the above-mentioned reasons.