Bob, I think with the changes that we are proposing, DITA 2.0
will handle all the types of safety messages that ANSI Z535.6
outlines.
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 1:10 PM, Bob Thomas wrote:
On another matter, ANSI Z535.6 makes provision for
different levels of safety messages: supplemental, grouped,
section, or embedded. Do you believe that the hazardstatement
model ought to support that, and if so, how?
Bob
Point taken. It
becomes basically a rendering stylesheet effort to make sure
the symbols end up in the right locations. As long as the
hazardsymbol moves into the messagepanel hierarchy the
biggest issue will have been solved.
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
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
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
--------
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
Time zone: Mountain (GMT-7)
--
Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Time zone: Mountain (GMT-7)
|