RE: Possible rework of hazard statement domain

[Amber Swope <amber@ditastrategies.com>]

Thanks, Kris. Iâ??ve asked Applied if we can use some of their hazard statements as examples.

A

 

 

From: Kristen James Eberlein <kris@eberleinconsulting.com>
Sent: Monday, August 26, 2019 7:26 AM
To: dita@lists.oasis-open.org; Amber Swope <amber@ditastrategies.com>
Subject: Possible rework of hazard statement domain

 

Hi, Amber.

Just circling back on this one.

Do you happen to know what ANZI535.6 says about multiple images in a hazard statement?

Also, it looks as if the images in the rendered hazard statement correspond to the child elements of <hazardstatement>:

• Left (yellow) image relates to either <typeofhazard> or <consequence>.
• Right (blue) image related to <howtoavoid>.

<hazardstatement type="danger">
            <messagepanel>
                <typeofhazard>HAZARDOUS VOLTAGE</typeofhazard>
                <consequence>Contact may cause electric shock or burn.</consequence>
                <howtoavoid>Read and understand manual before servicing</howtoavoid>
            </messagepanel>
            <hazardsymbol href="">            <hazardsymbol href=""></hazardstatement>

We could consider allowing <hazardsymbol> WITHIN <typeofhazard>, <consequence>, and <howtoavoid> ...

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 5/10/2018 8:38 PM, Amber Swope wrote:

Thanks for starting this discussion, Jang.

 

Because I see the symbol placement as separate from the info in the message panel, I donâ??t have an issue with <hazardsymbol> being outside of the <messagepanel>.

 

However, I do have requirements for the hazard symbols. We need to have a standard method for indicating the position and presentation order for symbols when there is more than one image.

 

Position: Indicate whether to present the image on the left or right side of message panel. The following example shows multiple images.

 

 

The current way one of my clients is handling this is to use the @align attribute on the <hazardsymbol> element. It isnâ??t pretty, but it provides instruction for the transform to place the image on the left or right of the message panel.

 

Example:

<hazardstatement type="danger">
   <messagepanel id="messagepanel_w4k_ll1_5db">
    <typeofhazard>HAZARDOUS VOLTAGE</typeofhazard>
    <consequence>Contact may cause electric shock or burn.</consequence>
    <howtoavoid>Read and understand manual before servicing.</howtoavoid>
   </messagepanel>
   <hazardsymbol href="electric_symbol.png" align="left"/>
   <hazardsymbol href="read_manual.png" align="right"/>
  </hazardstatement>

 

Presentation order: Indicate the order in which to present multiple images on either side of the message panel.

When there are multiple symbols that need to appear on the same side in a specific order, we need to be able to set the order. For my client with this situation, the transform is presenting the images in the order in which they are referenced; however, it might be good to explicitly indicate the presentation order with some attribute value.

 

 

From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Jang
Sent: Thursday, May 10, 2018 1:25 PM
To: DITA Technical Committee
Subject: Re: [dita] Proposal for a safety domain in DITA 2.0

 

Thanks to all for the feedback.

 

It is good to read that a bunch of companies are actually using the hazardstatement - and have adapted their rendering to make it work. I am OK with keeping the naming of elements so that there is no disruption of current materials. But I would still like to review the hazardstatement domain for DITA 2.0 and make sure it does comply with ANSI Z535.6 and it does cover all the options given by that standard.

 

To answer the question about differences between ANSI Z535 and ANSI Z535.6 - there are none. ANSI Z535 contains a number of sub-standards that define shapes, symbols, colours etc. of safety signs and criteria for their usage. The dot 6 standard concerns safety information in product manuals, instructions and other collateral materials and simply applies all the other dot standards to our domain of technical content.

 

There are a number of issues I would like to see changed when reviewing the hazardstatement domain for DITA 2.0:

 

1. The hazardstatement domain currently only implements the so-called Section Safety Messages. There are no specific provisions for Grouped Safety Messages (a topic that lists only safety messages and appears as Safety chapter in the ToC, or even as separate Safety Manual) and Embedded Safety Messages (which may appear as inline text but do show the signal word). Of course, the Grouped Safety Messages can be implemented as a topic with a body that only contains hazardstatements, and an Embedded Safety Message could be implemented as a <note>. It would have been nice if there was a consistent coverage of all safety messages in a single hazardstatement domain.

 

2. The current hazardstatement has a @type that simply copies the @type on <note>. ANSI Z535 recognises just 4 hazard levels and imposes very strict rules on when these hazard levels should be used. Also, the hazard level should not be defined in the <hazardstatement> but in the <messagepanel>, possibly as a new @level, which is mandatory and has only the four defined levels as values. When multiple <messagepanel> are combined in a single <hazardstatement>, the highest @level value determines the signal word, color, symbol and heading text for the entire <hazardstatement>.

 

3. The ANSI Z535.6 standard states that the info on how to avoid the hazard may be omitted when the type of hazard and/or consequence is clear enough in itself. The current content model lists <howtoavoid> as one or more - this should be changed to zero or more.

 

4. Incorrect position of the optional hazardsymbol. The current definition allows any number of hazardsymbols following the one or more messagepanel elements in a hazardstatement. This makes no sense whatsoever as the optional hazardsymbol is used as a graphical representation of a particular type of hazard - it should be part of the <messagepanel>. This allows a number of CAUTION level messages to be grouped under a single CAUTION header, each showing a specific symbol - such as crushed hands, sharp edges, laser beam, etc. 

 

5. The description of <hazardstatement> in the specs should include a clearer description of the hazard levels (which would be the values for the @level on <messagepanel>, not in a section named Example but as part of the specification text.

 

6. To keep consistency between Embedded, Grouped and Section safety messages, it might be useful to introduce a note-type hazard statement, which could be <hazardnote> and has the same @level as <messagepanel>. Such embedded safety notes appear either in a separate paragraph or as inline phrase, where only the signal word is used (with the defined formatting), followed by the safety message text.

 

The only disruptive change in the above list would potentially be moving the hazardsymbol into the messagepanel, where it belongs. I doubt that lots of companies are using multiple hazardsymbols in a grouped hazardstatement. For those companies that are using hazardsymbol a simple transform should be able to push it into the messagepanel.

 

Jang F.M. Graat
Smart Information Design
Amsterdam, Netherlands
Cell: +31 646 854 996

 

On 10 May 2018, at 19:39, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

 

I also am aware of multiple companies using <hazardstatement>. There are tons of manufacturing companies using DITA.

Jang, I don't think that default rendering (whether in DITA-OT or authoring tools) has any bearing on whether companies use the hazard statement domain. All companies that I work with create their own style sheets for rendering, whether for their authoring environments or published output.

Currently, I don't see the need for another safety domain. Perhaps the question should be "Are there enhancements or modifications to the hazard statement domain that we should make for DITA 2.0?"

Jang, are there use cases for which the current hazard statement domain is not sufficient?

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 5/10/2018 12:52 PM, Amber Swope wrote:

I have multiple clients using the hazard statement as currently structured and it would be disruptive to them if we removed support. They are using custom transforms to render the statements as required.

 

Thanks, Amber

 

From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Jang
Sent: Tuesday, May 8, 2018 10:05 AM
To: DITA TC
Subject: Re: [dita] Proposal for a safety domain in DITA 2.0

 

I guess these companies must have created their own rendering then, because until recently, none of the publishing tools did anything even remotely correct with it. But even if companies are using it, there are a number of things that are not correct about it when checking it against ANSI Z535.6, which is mandatory at least in the machinery industry.

 

So if we are checking with clients who are using the hazard statement, please also include feedback on whether these clients have done their own rendering transforms, and whether they have any comments about incompatibilities, incompleteness or hard-to-use features of the domains. Just the fact that companies are using it does not say it was well designed.

 

Kind regards

 

Jang F.M. Graat
Smart Information Design
Amsterdam, Netherlands
Cell: +31 646 854 996

 

On 8 May 2018, at 18:59, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

 

Jang, there are manufacturing companies that use the current hazard statement domain, so I cannot agree with your assertion that "hardly anyone is really using [hazard statements]."

Consultants on the TC, can we get a tally of your clients whom you know are using the hazard statement domain?

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 5/8/2018 12:38 PM, Mr. Jang Graat wrote:

The hazardstatement domain is very poorly designed. There are almost too many things wrong with it, from its placement in the base directory and inclusion in all document shells to the content model for the hazardstatement itself and poor naming of elements. Until very recently, none of the authoring and publishing tools for DITA have done anything even remotely right in rendering hazard statements. Which goes to show that hardly anybody is really using them.

I propose to rework the hazardstatement domain in DITA 2.0 to align it with the ANSI Z535.6 standard on safety information. The new domain should be called safety domain and allow all and only those safety notices and symbols that are covered by the ANSI Z535.6 standard. This includes not only the current hazardstatement (with necessary fixes and constraints applied to it) but also embedded safety notices which follow the same ANSI Z535.6 rules.

I am willing to invest time in implementing the required elements and do the necessary reality checks with users from various industries, so that DITA 2.0 will have a safety domain that is really being used.

I am not currently a voting member of the DITA TC but intend to reach and maintain that status going forward, so that I can become champion for this proposal and take it through the process.

Kind regards

Jang F.M. Graat
Smart Infornation Design
Amsterdam, Netherlands

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

 

--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php