Issue 12040 Proposal: Machine Industry Task specialization for DITA 1.2

The machine industry task domain is a specialisation of task with the purpose of providing a better framework for installation, commissioning and maintenance activities in the machinery industry. In the first step for DITA 1.2 an alignment with the S1000D standard is planned.

Longer description

Maintenance tasks would benefit from a more elaborate set of prerequisite elements for tools, spare parts, time and skill requirements. The introduction of these additional elements as specialisations from the prereq and closereq element would allow postprocessing of the xml files to extract useful information for a set of tasks that logically belong together.

Statement of Requirement

The current content model of the prereq element has been defined very open. Authors do not get any guidance within the prerequisites of a task. Information for support equipments, supplies or spare parts are required in the machinery industry but not defined in the dita content model of prereq.

To ensure a similar structural design in the prerequisites section it is important to provide authors with a common structure. The base structure for these prereqs can be derived from the S1000D standard, as this structure has been development for similar tasks.

Use Case

The machine industry task domain specialization would be used by all technical writers that write service manuals for installation, commissioning and maintenance of a machine. Typical for machine mainteance is that most tasks require tools and material. The ability to express tools, parts, time, skill level and prerequisite tasks in seperate elements would help them to structure these maintenance tasks in a more logical way.

Scope

The work to be done is a number of domain specialisations of existing elements with a more strict content. As such no major design work is to be expected. Depending on the results of the proposal "generic task type" this domain might be used in the standard dita task type as well as in the general task type.

This proposal is based on a technique planned for DITA 1.2, specializing a specialized element. As it is planned to use a replacement specialization of the prereq and closereq elements with the S1000D elements prelreq and postreq elements.

It is not the goal of the proposal to addapt the entire S1000D standard but to inherit ideas and techniques used within the S1000D standard but to offer a more open content model and not to follow the high restrictions of S1000D. But it must be guaranteed that specializer can limit the content model to a more S1000D restricted level.

For more details check the powerpoint presentation at:http://www.oasis-open.org/apps/org/workgroup/dita-machine-industry/document.php?document_id=26004

Technical Requirements

The following structure indicates some samples, for the detailed proposed DTD see the DTD files at: http://www.oasis-open.org/apps/org/workgroup/dita-machine-industry/document.php?document_id=25315
      <!ELEMENT prelreqs      ((%reqconds;)?, (%reqpers;)?, (%supequip;)?, (%supplies;)?,(%spares;)?,(%safety;)?)    >
      <!ELEMENT closereqs      (%reqconds;)    >
      
      <!ELEMENT reqconds       ((%noconds;) | ((%reqcond;) | (%reqcontp;))+) 		 >
      <!ELEMENT noconds       EMPTY                            >
      <!ELEMENT reqcond       (%listitem.cnt;)*                            >
      <!ELEMENT reqcontp            (%listitem.cnt;)*                            >
      
      <!ELEMENT supequip       ((%nosupeq;)|(%supeqli;)) 		 >
      <!ELEMENT nosupeq    EMPTY >
      <!ELEMENT supeqli       (%supequi;)+                                      >
      <!ELEMENT supequi            (%listitem.cnt;)*                            >
 

Costs

High: this proposal requires the final development of a domain ent and mod file and to provide the required stylesheet support in the DITA-OT

Benefits

The benefits for technical writers are mostly related to the possibilities of automatic data extraction from the available data :
  • The use of a prerequisite tool (support equipment) list should allow automatic extraction of a tool list for a given bundle of tasks. A symbol could be used in front of this section to indicate the availability of the prerequisite list of tools.
  • The use of a prerequisite parts list (spares) should allow automatic extraction of a parts list for a given bundle of tasks. A symbol could be used in front of this section to indicate the availability of the prerequisite list of parts.
  • The indication of the time required should allow automatic calculation of the total time needed to perform a bundle of tasks. (in person element) A symbol could be used to indicate the location of this information
  • The indication of the required skill level should allow automatic determination of the overall skill level required to perform a bundle of tasks. The presence of the skill level could also be used to extract the list of tasks that should be covered in a training for a given skill level. A symbol could be used to graphically indicate the location of this information or to indicate the skill level.
  • The indication of the prelreqs and postreqs should allow automatic extraction of the flow of operation.

Since there is no real overhead compared to the current way of working it is expected that most technical writers that need to create installation and maintenance task will use the specialised prerequisite. Even if they do not plan to automatically extract information, the information is presented in a more logical way and the available templates will serve as a placeholder for the pieces of the task that need to be documented.

The impact to the existing documentation set is minimal. If a technical writer is already using the above information in the existing prerequisite element, it is easy to assign a new element to the existing information.