Re: [dita] <hazardsymbol> and the redesign of the hazard statement domai

On 10 Sep 2019, at 18:32, Bob Thomas <bob.thomas@tagsmiths.com> wrote:

In response to Jang 9/10/2019,

As I have said before, the only right model forÂhazardstatementÂis reached by moving the zero or moreÂhazardsymbolÂelements to be children of messagepanel. Pushing them intoÂtypeofhazardÂconsequences orÂhow toavoidÂdoes not make any sense, as there may be a mix of specific hazard type and how to avoid symbols (face masks, gloves etc).Â

This makes no sense. The possibility of a mixture of hazard-type, avoidance, and consequence safety graphics is precisely why you need to allow hazardsymbolÂwithin the messagepanel child elements. When you make hazardsymbolÂavailable only as a child messagepanel, there is no way to determine the purpose of the hazardsymbolÂwithout resorting to outputclass values or naming conventions. This ambiguity is avoided when hazardsymbol*Âis allowed as a child of hazardtype, consequence, and howtoavoid.

For example, consider a messagepanel with safety graphic for an explosion hazard and a safety graphic with a no-flame icon for avoidance. With hazardsymbol*Âas a direct child of messagepanel there is no way to determine which graphic serves which purpose. With hazardsymbol* allowed under hazardtypeÂand under avoidance, the graphic's purpose is clear and there is no ambiguity.

Best regards,

Bob Thomas

On Tue, Sep 10, 2019 at 5:59 AM Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

Thanks for responding.

I think you are digging in your heels and insisting that your recommendation is the correct one, rather than considering other possibilities.

A compelling reason for associating <hazardsymbol> with the child elements of <messagepanel> to facilitate reuse. Given the following markup, option B allows for more reuse. Option A requires that the unit of reuse is the <messagepanel> element, while option B enables reuse at a more granular level.

Option A

<hazardstatement type="caution">
Â <messagepanel>
ÂÂÂ <typeofhazard>HAZARDOUS VOLTAGE</typeofhazard>
ÂÂÂ <consequence>Contact may cause electric shock or burn.</consequence>
ÂÂÂ <howtoavoid>Read and understand manual before servicing</howtoavoid>
ÂÂÂ <hazardsymbol keyref="hazardous-voltage"/>
ÂÂÂ <hazardsymbol keyref="read-manual"/>
Â </messagepanel>
</hazardstatement>

Option B

<hazardstatement type="caution">
Â <messagepanel>
ÂÂÂ <typeofhazard>
ÂÂÂÂÂ <hazardsymbol keyref="hazardous-voltage"/>
ÂÂÂÂÂ HAZARDOUS VOLTAGE
ÂÂÂ </typeofhazard>
ÂÂÂ <consequence>Contact may cause electric shock or burn.</consequence>
ÂÂÂ <howtoavoid>
ÂÂÂÂÂ <hazardsymbol keyref="read-manual"/>
ÂÂÂÂÂ Read and understand manual before servicing.
ÂÂÂ </howtoavoid>
Â </messagepanel>
</hazardstatement>

Best,
Kris

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

On 9/10/2019 2:02 AM, Jang wrote:

Hello Kris,

As I have said before, the only right model for hazardstatement is reached by moving the zero or more hazardsymbol elements to be children of messagepanel. Pushing them into typeofhazard consequences or howtoavoid does not make any sense, as there may be a mix of specific hazard type and how to avoid symbols (face masks, gloves etc).Â

As for real life examples: I have seen tons of grouped hazard statements in my 15 years of writing manuals in the machinery industry (before DITA). I have no access to those materials as I left the industry long ago. The grouped hazard statement in your first example is exactly what I have seen many times. The second one is very untypical as it seems to subordinate the signal word to the hazard symbols on either side. From an information design viewpoint, that is not a good solution.

Kind regards

Jang F.M. Graat

Smart Information Design

Amsterdam, Netherlands

Cell: +31 646 854 996

<icon-facebook.png><icon-twitter.png><icon-linkedin.png><icon-github.png>

On 9 Sep 2019, at 22:16, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

Any feedback?

Best,
Kris

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

-------- Forwarded Message --------

Subject: [dita] <hazardsymbol> and the redesign of the hazard statement domain

Date: Sun, 8 Sep 2019 19:41:36 -0400

From: Kristen James Eberlein <kris@eberleinconsulting.com>

To: DITA TC <dita@lists.oasis-open.org>

Background

Pretty much everyone who has chimed in on this thread agrees that we need to make changes regarding where <hazardsymbol> is permitted. But ... Different people have very different ideas about where it should be allowed.

Current content model

Below is markup for a simple hazard statement and its rendered output:

ÂÂÂÂÂÂÂ <hazardstatement type="warning">
ÂÂÂÂÂÂÂÂÂÂÂ <messagepanel>
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <typeofhazard>GENERAL HAZARDS</typeofhazard>
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <consequence>Overriding or defeating the interlocks will expose personnel to
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ hazardous conditions.</consequence>
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <howtoavoid>DO NOT override or defeat the interlocks unless specifically directed to
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ do so in the procedures. When directed to override an interlock, follow all
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ safety procedures and apply HEI (Lockout/Tagout) procedures as
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ necessary.</howtoavoid>
ÂÂÂÂÂÂÂÂÂÂÂ </messagepanel>
ÂÂÂÂÂÂÂÂÂÂÂ <hazardsymbol keyref="warning"/>
ÂÂÂÂÂÂÂ </hazardstatement>

Note that each <hazardstatement> element can contain:

One or more <messagepanel>

Zero or more <hazardsymbol>

The <hazardstatement> element might be rendered as follows:

<hazard-one-image.png>

Issues with the current content model

Obviously the current content model works fine for the simple hazard statement provided above. But what happens when a hazard statement has multiple message panels? Multiple hazard symbols? Then it is unclear which symbol is associated with which message panel -- or even which child component of the message panel. Does a image represent the "type of hazard" or "how to avoid" the hazard? This might matter if a company's style calls for rendering one type of image on the left and another type of image on right.

Current suggestions for modifying the content model

Person
Suggestion
Comments

Jang Graat
Associate <hazardsymbol> with <messagepanel>
Requires changing the specialization base of <messagepanel> and its child elements

Toshihiko Makita,
Antenna House
Associate <hazardsymbol> with <messagepanel>; allow only a single <hazardsymbol>
Not an option that we can consider. DITA 1.2-13 allowed multiple <hazardsymbol>, and we have many clear use cases for multiple <hazardsymbol>

Kris Eberlein
Associate <hazardsymbol> with the child elements of <messagepanel>:

<typeofhazard>

<consequence>

<howtoavoid>

Requires expanding the content model of the following elements to include zero or more<hazardsymbol>:

<typeofhazard>

<consequence>

<howtoavoid>

This also might (better) accommodate designs where a company wants to use the hazardsymbol image as a bullet point. From dita-users:

" I am having difficulty placing symbols exactly where I want them (currently we use a symbol in a similar way to a bullet point) â but that may be due to my lack of experience with DITA."

Realistically, any company using the hazard statement domain is going to need to invest in custom stylesheets.

Assumptions that drive design choices

There IS a reason for the current design; the only reason that multiple <messagepanel> elements are permitted is that Chris Kravogel anticipated that companies might want to have hazard statements that presented the information in multiple languages. (KJE: This is not a use case that I have seen in real world usage, at least yet. And the design does not allow for presenting the "signal word" -- based on the value of the @type attribute -- on <hazardstatement> in multiple languages )

Use cases that the original design did not consider:

Combining multiple message panels with different information (and hazard symbols)

<image001.png>
This is a real world example from a Comtech Services client, who uses this sort of rendering in a "Safety" chapter. It also parallels what ANSI Z 535.6 calls "grouped safety messages" and "section safety messages".

Single message panel but with hazardsymbol images placed based on what they represent:

<image001.jpg>
This is a real world example from Applied Materials, a company that Amber and I and Comtech have all worked with, I think.

What do you all think? Which option is best? And do we continue to allow <hazardsymbol> to be associated with <hazardstatement>?

--
Best,
Kris

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

--

Bob Thomas
+1 720 201 8260

Skype: bob.thomas.colorado

Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype

Time zone: Mountain (GMT-7)

dita message