DITA Proposed Feature # 12024: Hazard Statement Domain

An issue of high importance in documents for the machinery industry are hazard statements. As machines do have moving, rotating, heating or current-carrying parts. False manipulations can lead to serious injury or even death. ANSI and ISO have defined standards for hazard statements which are not yet reflected in the dita standard. The goal of this proposal is to close that gap.

Longer description

One of the major statements dita-opposers make regarding DITA in the machinery industry is the fact that DITA is not forseeing extended elements for hazard statements. E.g. the actual product brochure of the SCHEMA ST4 XML content management system states The DITA-Standard has been developed for the IT-industry and covers mainly the requirements for technical documentation for software. Other industries do have higher and stricter requirements for the product documentation. As an example, in the machinery industry, the requirements for hazard statements are explicitly more comprehensive defined as it is forseen in the DITA standard. Even organizations e.g. the German TEKOM officially proclaims, that the DITA standard is not ready for the machinery industry especially due to the fact of the missing support of hazard statements.

The organizations ANSI and ISO have defined standards for hazard statements in their ANSI Z535 and ISO 3864-2 standard. They are defined in many details, and this standard can be addopted 1:1 into the DITA standard by a specialization of the note element.

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

Statement of Requirement

The need is to update the note element in adding the two values warning and notice to the type attribute, as well as creating an entire domain for hazard statements, accordingly to the ANSI/ISO standard.

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

Use Cases

There are mainly two use cases for hazard statements:

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

Scope

Major: the first part updating the type attribute is a minor work, but the hazard statement domain will need far more work to implement. Even when the DTD is more-or-less developed, there is a high need in updating the stylesheets to follow the rendering requirements according to the ANSI.

Technical Requirements

There are two modifications required:

  1. Update of the value list of the type attribute in the note elements. Adding the values caution1, caution2, warning and notice.
  2. Creating an hazard statement domain, following the full ANSI/ISO standard for hazard statments.

note DITA 1.1

       <! ATTLIST   note 
                type       (note | tip | fastpath | restriction | important | remember| attention | caution | danger | other) #IMPLIED  
       

proposal note DITA 1.2

       <! ATTLIST   note 
                type       (note | tip | fastpath | restriction | important | remember| attention | notice | caution | caution1 | caution2 | warning | danger | other) #IMPLIED  
       

proposal hazardstatement DITA 1.2

	<!ELEMENT hazardstatement ((%messagepanel;)+, (%symbol;)*)>
	<! ATTLIST   hazardstatement 
                type       (note | tip | fastpath | restriction | important | remember| attention | notice | caution | caution1 | caution2 | warning | danger | other) #IMPLIED 
                
	<!ELEMENT messagepanel ((%typeofhazard;), (%consequence;)*, (%howtoavoid;)+)>
      

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=22515

New or Changed Specification Language

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

Costs

Benefits

More acceptance of DITA in the machinery industry. Better support of hazard statements in DITA based documentation.