OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] Software Bias in Current DITA Design and Documentation

A few clarifications

1) IBM provides services, hardware and software - it is not essentially a software company.

2) Historically, DITA was created by a team that included representatives from the hardware ID community within IBM

3) Both hardware and software have a history of being organized around functional tasks rather than user tasks, and both communities are struggling to improve task orientation - but in the meantime, the current task design supports both approaches, and allows user communities to make their own decisions about task atomicity. If a set of tasks always belongs together, they can be authored in a single unit; if they only sometimes belong together, they can be authored separately. The out-of-the-box task doctype explicitly supports task nesting as the more flexible of the two options.

4) The language spec examples were created by a writer with a background in software, and the first set of specializations include several software-specific domains. That is the extent of the software bias to my knowledge.

Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead

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

01/17/2007 01:02 PM

[dita] Software Bias in Current DITA Design and Documentation

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

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

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.


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


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]