OASIS Darwin Information Typing Architecture (DITA) TC

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

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