OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita-lightweight-dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: A Need for Note

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.



Keith Schengili-Roberts
DITA Information Architect / DITA Specialist
825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1
tel  + 1 514 279-4942  /  toll free + 1 877 279-4942 


Interested in attending? Visit our event website for more information. 

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]