Annotations Best Practices

This summary of "best practices" in creating annotations for RIM, Vocabulary and other content is drawn from recommendations of the HL7 Technical Editing Project made to M&M in May, 2008. These style rules have been used to revise all annotations in the HL7 Reference Information Model.

HL7 Technical Editing Project - Annotation Style Guide
Annotation Type	Definition	Used By	Criteria
Definition	An explanation of the meaning of the element. Intended to explain the semantics of the element. Should be sufficient to differentiate the semantics of the element from other sibling elements.	Internal, Designer, Consumer, Implementer, Academic	A definition is a noun phrase. It SHALL NOT include examples or explanations of usage. It MAY include clarifying sentences. A definition addresses the semantic space of the feature: it SHALL NOT constrain data types (e.g., "a code indicating . . .").
Example	A free-text example of content that might be used in or for the element. Used to help better understand the usage and scope of the element.	Internal, Designer, Consumer, Implementer, Academic	Examples SHALL include three separate values that illustrate the semantic domain. Scenarios MAY help put the examples in context, but the scenario without the value is a usage note, not an example.
UsageNotes	Advice to designers and/or implementers on how to make use of an element and/or how not to make use of an element.	Internal, Designer, Academic	Usage Notes illustrate how a reader might implement a feature. They SHALL NOT repeat vocabulary specifications: repetition introduces maintenance and synchronization issues. They are prospective: they SHALL NOT repeat rationale.
Comment:	Vocabulary is sometimes critical to explanation of usage, but it should be presented as exemplary, not as a full specification.
Rationale	An explanation of why the element is necessary or potentially useful within this context. May also explain why the element is expressed and constrained in the way it is.	Internal, Designer, Academic	Rationale explains why a particular feature is designed the way it is. It is retrospective: it SHOULD NOT be necessary for an implementer to understand a rationale. Explanations of how the feature is to be used SHALL NOT be included here: they are Usage Notes.
Requirements	Documents the requirements that drove the specification of the artifact. May include references to other standards or literature describing the appropriate data elements and constraints.	Internal, Designer, Academic
Constraint	A formal, testable limitation on the use, representation or value associated with the current element.	Internal, Designer, Consumer, Implementer, Academic	Constraints document objective constraints that can be modeled in OCL. They SHALL NOT repeat information that can be inferred from attributes (e.g., “mandatory,” “CNE”). Semantic constraints that cannot be formalized SHALL be documented in usage notes.
Comment:	If non-formalizable constraints are not allowed, and normative content excludes usage notes, then those constraints won’t be normative. Recommendation: allow non-formalizable constraints here
OpenIssue	Notes to designers, balloters and implementers about outstanding concerns that remain to be resolved.	Internal, Designer, Academic
Comment:	Open issues might identify to issues identified for committee or Harmonization review, or they may identify standing issues for publication. These may or may not be a single category.
DesignComments	Internal development notes about why particular design decisions were made, outstanding issues and remaining work. Not intended for external publication.	Internal
DeprecationInfo	Information relating to the deprecation of the element, including instructions on why the element is no longer required and/or how the same information should now be handled.	Internal, Designer, Consumer, Implementer, Academic	For deprecated features only