Software Bias in Current DITA Design and Documentation

["W. Eliot Kimber" <ekimber@innodata-isogen.com>]

In my review of the latest reference spec and also in working through 
some legacy conversion issues, I'm starting to conclude that there is 
currently a software bias in both the DITA design and in the 
documentation that reflects an underrepresentation of hardware 
documentation requirements.

For example, in the introductions to concept, reference, and task, all 
the examples are software examples (with the exception of recipes). I 
didn't see any examples of hardware-specific uses, such as parts lists, 
assembly procedures, and so on.

It's not surprising that this bias exists given that IBM is essentially 
a software company and DITA has historically been driven by the needs of 
software documentors.

I think that this bias becomes a problem specifically in tasks, where 
there is a somewhat different documentation practice for hardware and 
software.

In particular, hardware tasks are often organized and grouped based on 
the subsystem being operated on and the set of tools and consumables 
required, whereas software tasks, which don't normally involve tools or 
consumables, are more naturally standalone.

Thus the current design of the task topic does not provide for 
describing, under single context and set of prerequisites, a set of 
distinct but related tasks that are intended to be performed as a unit 
and that are not really usefully pulled out as standalone tasks, i.e., 
removal, repair, test, and replacement of a single primary part or 
subsystem.

Apart from adding a few hardware examples to the docs, there's not 
anything we can do about this for 1.1 of course, but I'd definitely like 
to visit the issue of more sophisticated task structures for the next 
development phase.

Cheers,

Eliot
-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
8500 N. Mopac, Suite 402
Austin, TX 78759
(214) 954-5198

ekimber@innodata-isogen.com
www.innodata-isogen.com