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.
Cheers!
