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

[Michael Priestley <mpriestl@ca.ibm.com>]

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
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

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

01/17/2007 01:02 PM

To	<dita@lists.oasis-open.org>
cc
Subject	[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 
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