I am working on the stage two proposal for issue #164: "Redesign
hazardstatement".
This proposal should cover requirements brought forth by multiple
DITA TC members:
Dawn Stevens's requirements and use cases are clear and straight
forward.
Jang Graat's requirements and use cases are less clear to me.
Below, I annotate his e-mail with my questions and observations.
Thanks to Scott Mcgrath, OASIS, for arranging for me to get a copy
of the 2017 release of ANSI Z535.6.
Based on my research, I recommend the following:
- Expand the content model of <howtoavoid> to also permit
<ol> and <ul>
- Constrain the values of the type attribute on
<hazardstatement> to "danger", "warning", "caution", and
"notice"
- Improve the element-reference topic for
<hazardstatement> to include definitions of "danger",
"warning", "caution", and "notice" that match those in ANSI
Z535.6
- (Optional) Change the specialization base for
<messagepanel>, <typeofhazard>, <consequence>,
and <howtoavoid> to <div>
I can't recommend that we make additional changes without having
clearer user requirements ... We just do not have the expertise in
this area.
I'd really welcome someone else vetting my research and
conclusions!
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 4:24 PM, Jang wrote:
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.
<kje>I don't know if we need to cover ALL
options given by the standard; it really gives companies a lot of
flexibility.</kje>
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.
<kje>I disagree with Jang's assertion
that the hazard statement domain only implements section safety
messages.
Based on my reading of the 2017 release,
ANSI Z535.6 defines four types of safety messages:
- Supplemental directives:
- "Supplemental directives are messages
about other safety messages. Supplemental directives do not
address specific hazards, but instead provide information
that promotes awareness and use of specific safety messages
(e.g., grouped, section, or embedded safety messages; or
product safety signs and labels) or other safety-related
information." Page 3, ANSI Z535.6-2011 (R2017)
- Could be a specialization of note; can
be accommodated with current <note>.
- Grouped safety messages
- "Safety messages that are collected or
grouped in a document or section of a document devoted
primarily or exclusively to safety information." Page 3,
ANSI Z535.6-2011 (R2017)
- Can be handled with a topic in
existing bookmap or map -- no need to add to the standard.
- Section safety messages
- "Safety messages that apply to entire
sections, subsections, or multiple paragraphs or procedures
within a document. These messages apply to larger units of
information than embedded safety messages and typically
appear at the beginning of the section to which they apply."
Page 3, ANSI Z535.6-2011 (R2017)
- I think the <hazardstatement>
element can be used for this.
- Embedded safety messages
- "Safety messages that apply to a
specific part of a section, a paragraph, a particular
procedure or part of a procedure, a particular sentence,
etc. in a document. These messages apply to smaller units of
information than do section safety messages and are
integrated within procedures or other text." Page 4, ANSI
Z535.6-2011 (R2017)
- My personal take is this is how
<hazardstatement> is typically used.</kje>
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>.
<kje> Yes, ANSI Z535 only recognizes
DANGER, WARNING, CAUTION, and NOTICE. I could get behind
constraining the values for @type on <hazardstatement.
Constraining attributes is a nuisance, and I suspect that is why
it was not done for the DITA 1.2 release.
While yes, a <hazardstatement>
element can contain multiple <messagepanel> elements, I
have not seen ANYONE trying to do this.
Section 5.1.2 Multiple Hazard
Identification contains the following text: "When one signal
word is used to identify multiple safety messages and the
messages are classified at different levels of risk, the signal
word corresponding to the greatest risk level shall be used."
Page 5, ANSI Z535.6-2011 (R2017)
This, of course, could be accommodated by
implementations grouping hazard statements based on the signal
word.</kje>
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.
<kje>The ANSI Z535.6 standard allows
A LOT of flexibility, especially for grouped safety
messages.
"... Where information regarding the
hazards, consequences, or avoidance is similar or identical for
several or all grouped safety messages, such information may be
stated once and need not be repeated for each individual
message.
When information regarding the hazards,
consequences, or avoidance is readily inferred, such information
may be omitted. In addition, consequence information for a
grouped safety message may be omitted if general consequences of
failure to comply with all of the grouped safety messages are
provided in a supplemental directive preceding the grouped
safety messages." Section 7.2, page 9, ANSI Z535.6-2011 (R2017)
I don't think we want to make all the child
elements of <hazardstatement> optional!
</kje>
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.
<kje>I can buy this, but again, I
have not seen implementations producing hazards statements that
contain multiple message panels.
And if we factor in multiple hazards
symbols, I'd think that the hazard symbol should be associated
with the specific child element of <messagepanel>, not
<messagepanel>. Note Amber Swope's e-mail with an example
of a simple hazard statement with two symbols.</kje>
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.
<kje>I can agree with this, especially
if we constrain the values of the @type attribute on
<hazardstatement>.</kje>
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
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
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.
Jang F.M.
Graat
Smart Information Design
Amsterdam, Netherlands
Cell: +31 646 854 996
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