This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "Annotations Best Practices"

From HL7Wiki
Jump to navigation Jump to search
Line 1: Line 1:
−
This is a place-holder until such time as the Vocabulary committee provides a formal set of recommendations
+
This summary of "best practices" in creating annotations for RIM, Vocabulary and other content is drawn from recommendations of the HL7 Technical Editing Project.  These style rules have used to revise all annotations in the HL7 Reference Information Model.
  
−
* Definitions should be expressed in one sentence, two at most
+
{| border="0" cellspacing="0" cellpadding="3"
−
* Definitions should focus on what something is, not what it is not.  (Usage notes may provide clarification by identifying exclusions and relationships to other concepts)
+
 
−
* Definitions should not be tautological (i.e. do not use a term to define itself)
+
|-
−
* Definitions should be full sentences
+
| align="center" colspan="4" style="background-color: #99CC99" | '''HL7 Technical Editing Project - Annotation Style Guide'''
 +
|-
 +
| align="center" style="background-color: #CCFF99" | Annotation Type
 +
| align="center" style="background-color: #CCFF99" | Description
 +
| align="center" style="background-color: #CCFF99" | Used By
 +
| align="center" style="background-color: #CCFF99" | Criteria
 +
 
 +
|-
 +
| valign="top" |'''Definition'''
 +
| valign="top" |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.
 +
| valign="top" |Internal, Designer, Consumer, Implementer, Academic
 +
| valign="top" |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 . . .").
 +
 
 +
|-
 +
| valign="top" style="background-color: #E7E7FF"|'''TypeName'''
 +
| valign="top"  style="background-color: #E7E7FF"|Description
 +
| valign="top"  style="background-color: #E7E7FF"|Users
 +
| valign="top"  style="background-color: #E7E7FF"|Rules of structure
 +
 
 +
|-
 +
| valign="top"|'''TypeName'''
 +
| valign="top"|Description
 +
| valign="top"|Users
 +
| valign="top"|Rules of structure
 +
 
 +
|-
 +
| valign="top" style="background-color: #E7E7FF"|'''TypeName'''
 +
| valign="top"  style="background-color: #E7E7FF"|Description
 +
| valign="top"  style="background-color: #E7E7FF"|Users
 +
| valign="top"  style="background-color: #E7E7FF"|Rules of structure
 +
 
 +
|-
 +
| valign="top"|'''TypeName'''
 +
| valign="top"|Description
 +
| valign="top"|Users
 +
| valign="top"|Rules of structure
 +
 
 +
|-
 +
| valign="top" style="background-color: #E7E7FF"|'''TypeName'''
 +
| valign="top"  style="background-color: #E7E7FF"|Description
 +
| valign="top"  style="background-color: #E7E7FF"|Users
 +
| valign="top"  style="background-color: #E7E7FF"|Rules of structure
 +
 
 +
|-
 +
| valign="top"|'''TypeName'''
 +
| valign="top"|Description
 +
| valign="top"|Users
 +
| valign="top"|Rules of structure
 +
 
 +
|-
 +
| valign="top" style="background-color: #E7E7FF"|'''TypeName'''
 +
| valign="top"  style="background-color: #E7E7FF"|Description
 +
| valign="top"  style="background-color: #E7E7FF"|Users
 +
| valign="top"  style="background-color: #E7E7FF"|Rules of structure
 +
 
 +
|-
 +
| valign="top"|'''TypeName'''
 +
| valign="top"|Description
 +
| valign="top"|Users
 +
| valign="top"|Rules of structure
 +
 
 +
|-
 +
| valign="top" style="background-color: #E7E7FF"|'''TypeName'''
 +
| valign="top" style="background-color: #E7E7FF"|Description
 +
| valign="top" style="background-color: #E7E7FF"|Users
 +
| valign="top" style="background-color: #E7E7FF"|Rules of structure
 +
 
 +
|-
 +
| valign="top"|'''TypeName'''
 +
| valign="top"|Description
 +
| valign="top"|Users
 +
| valign="top"|Rules of structure
 +
 
 +
 
 +
|}

Revision as of 14:45, 9 June 2010

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

HL7 Technical Editing Project - Annotation Style Guide
Annotation Type Description 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 . . .").
TypeName Description Users Rules of structure
TypeName Description Users Rules of structure
TypeName Description Users Rules of structure
TypeName Description Users Rules of structure
TypeName Description Users Rules of structure
TypeName Description Users Rules of structure
TypeName Description Users Rules of structure
TypeName Description Users Rules of structure
TypeName Description Users Rules of structure
TypeName Description Users Rules of structure


Retrieved from "https://wiki.hl7.org/w/index.php?title=Annotations_Best_Practices&oldid=37616"