| Keith’s email makes me feel better about my poor technical writing practices as a confessed (ab)user of the “note” tag in DITA. I think it would not be terribly difficult to bring it into out Lightweight DITA flavors. Like I mentioned yesterday, I missed the “note” tag a lot when I was creating the demo in https://github.com/VT-CHCI/mixedlightweightdita. And if we incorporate types of caution, warning, and danger, I also vote for including “trouble.” I gave a lecture just yesterday here at Virginia Tech about the 1.3 troubleshooting topic, and it made a lot of sense (to the students) to bring back the “Support error recognition and recovery” rule in DITA. I even had a pic of Jack Carroll in my slides. So, I would love to keep some troubleshooting info in Lightweight DITA if we allow notes.
Carlos
--- Carlos Evia, Ph.D. Director of Professional and Technical Writing Associate Professor of Technical Communication Department of English Center for Human-Computer Interaction Virginia Tech Blacksburg, VA 24061-0112 (540)200-8201
I've talked to some of my colleagues who have clients in the machine industry domain, and they agree that the need for the note element, and more specifically, in the context of being able to provide a warning or caution.
At the last meeting Michael brought up the good point that using a note is sometimes a sign of poor technical writing, as its message could often be incorporated elsewhere within the topic. Given the following example of emu wrangling:
<note type="warning">Emus are highly unpredictable birds, and have a nasty temper. Emu egg fetching may result in bodily harm for the unwary.</note>
...you could instead write the topic so that you include a step instructing the user to have someone stand by with a first-aid kit, or other steps guaranteed to soothe the savage beast, or perhaps simply advocate becoming a vegan.
While not emu farming-related, the European Machine Directive and ISO 26514 for software instructions both include some form of notice or note block in their standard both with 3 levels of danger:
- Danger level 0 (note/notice) (e.g. Emus are not nice birds.)
- Danger level 1 (ATTENTION/CAUTION) – material damage (e.g. Unrestrained emus may cause damage during attempted egg snatching.)
- Danger level 2 (WARNING) – possibility to get injured/kills (e.g. Emus have been known to inflict bodily injury on would-be egg snatchers.)
- Danger level 3 (DANGER) – certainty of get injured/killed (e.g. Improper preparation for emu egg snatching may result in the ridiculous, though undoubtedly messy, death of the egg snatcher.)
Given that the note element is used in full DITA as the mechanism for warnings and cautions through @type, we'd recommend retaining the note element along with explicit @type values of caution, warning and danger.
There's the argument that the note element might be sufficient if we talking about a SME entering a note about how nasty emus can be if there's the understanding that a technical writer using full DITA could change that to a full note type="warning", but our thinking is that some sort of caution/warning/danger mechanism ought to be available to the SME directly, as they would be able to correctly assess the threat level.
Cheers!
-
Keith Schengili-Roberts DITA Information Architect / DITA Specialist IXIASOFT 825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1
<OutlookEmoji-1457643010967_UC2016-logo.jpg.jpg>
Interested in attending? Visit our event website for more information.
|