DITA Machine Industry SC - MI02 - Note in Step - Revision 1 (IssueNumberMI02-Rev1.htm)

["Gerald Goetz" <goetz@noxum.com>]

I am sending you an updated version of Issue Number MI02 - Note in Step.

The proposal now also contains references to international guidelines. Thanks
to Roland Schmeling from TUEV-Sued and Willy Lebherz from Ifco-Experts for
their input (via Chris Kravogel).

Kind Regards,

Gerald Goetz
Noxum GmbH
Beethovenstr. 5
97080 Würzburg

Tel: +49 931 4 65 88 442
Fax: +49 931 4 65 88 599
 
Handelsregister: HRB 6212, Amtsgericht Wuerzburg Vertretungsberechtigte Geschaeftsfuehrer:
Norbert Klinnert, Volker Roemisch, Michael Stegmann

Title: DITA Proposed Feature # MI02 - Note in Step

DITA Proposed Feature # MI02 - Note in Step

Relax the content models of step and substep. Allow the elements note and hazardstatement (proposed new domain in DITA 1.2) to be placed before cmd within step and substep.

Longer Description

Problem

International guidelines require hazard statements to appear directly before a command instructing the user. Section 6.9.2 of IEC 62079:2001, EN 62079 and section 8.2 of ISO/IEC Guide 37 (1995) demand that hazard statements appear at the right time / right place in the instruction text. There is no doubt that the right time is when the danger still can be avoided. Passages in ANSI Z535 demand that the hazard statement must be recognized by the reader before the potential danger occurs. The task topic in DITA 1.1 does not support this requirement.

The current DITA 1.1 content models for step and substep do not support the placement of an element note (or the new domian hazardstatement) directly before an element cmd when more than one element step is present.

The elements context and info do allow note but context only supports notes / hazardstatements for all steps following and info only supports a note / hazardstatement after a command.

Solution

Allow the Elements note and hazardstatement as optional elements before cmd.

Scope

The changes in the content model are minor. The elements note and hazardstatement are already present. The content models affected are both defined in just one file:task.mod. All DITA 1.1 documents are still valid as the elements are not new and optional in their container elements.

Benefits

This feature would enhance the adoption of DITA in the machine industry and other areas. It would furthermore make technical documentation produced with DITA compliant with international guidelines and product liability requirements.

Use Case

The author describes a task with several steps. One step / substep requires a specific hazard statement like a warning. The author inserts the specific hazard statement (element note or hazardstatement) right before the cmd element. The author is not limited to place the hazard statement in the context element or the info element after the command.

Technical Requirements

The content models of step and substep would have to be modified.

Element step before modification:

<!--                    LONG NAME: Step                            -->
<!ELEMENT step          (%cmd;, 
                         (%info;  |%substeps; | %tutorialinfo; |
                          %stepxmp; | %choicetable; | %choices;)*, 
                         (%stepresult;)? )                           >

Element step after modification

<!--                    LONG NAME: Step                            -->
<!ELEMENT step          ((%note;| %hazardstatement;)*,
                          %cmd;, 
                         (%info;  |%substeps; | %tutorialinfo; |
                          %stepxmp; | %choicetable; | %choices;)*, 
                         (%stepresult;)? )                           >

Element substep before modification:

<!--                    LONG NAME: Sub-step                        -->
<!ELEMENT substep       (%cmd;, 
                         (%info; | %tutorialinfo; | %stepxmp;)*, 
                         (%stepresult;)? )                           >

Element substep after modification

<!--                    LONG NAME: Sub-step                        -->
<!ELEMENT substep       ((%note;| %hazardstatement;)*,
                          %cmd;, 
                         (%info; | %tutorialinfo; | %stepxmp;)*, 
                         (%stepresult;)? )                           >

Costs

Minimal. Change of two content models. No new elements / domains are introduced. The output of the publishing modules of the DITA Open Toolkit has to be validated.

Related Proposals

DITA Proposed Feature # 05 (Align note or a new domain with ISO and ANSI standards for hazard statements.)

Time Required

Two person hours for the DTD modification and the proper documentation (this does not include layout modifications in the DITA Open Toolkit).