[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]