View Revision MarksHide Revision Marks

Version 3 Publishing Facilitator's Guide

Chair of Publishing Committee / Helen Stevens

Gordon Point Informatics
Publishing Facilitator / Joann Larson

Kaiser Permanente
Editor / Donald Lloyd

Health Level Seven, Inc.

Last Published:03/26/20068:48PM

HL7® Version 3 Standard, © 2005 Health Level Seven®, Inc. All Rights Reserved.

HL7 and Health Level Seven are registered trademarks of Health Level Seven, Inc. Reg. U.S. Pat & TM Off

Table of Contents

Preface

i Notes to Readers

ii Acknowledgements

iii Changes from Previous Release

iv Known Issues & Planned Changes

1 Overview

1.1 Introduction and Scope

2 Roles and Responsibilities

2.1 Publishing Committee Leadership

2.2 Publishing Facilitators

2.3 Technical Publications Manager

3 Publishing Schedule

4 Reference Documents

5 Style Guide for Narrative Content

5.1 Language

5.1.1 Use of SHALL, SHOULD and Other Modal Verbs

5.2 Capitalization

5.2.1 Section Headings

5.2.2 Key Terms

5.2.3 Titles

5.3 Commonly Used Grammar Conventions

5.3.1 A and An Convention

5.3.2 Version Expression

5.3.3 The Use of Commas in a Series

5.3.4 Quotation Marks and Punctuation

5.4 Lists

5.5 Spelling Conventions

5.6 Tables

5.7 Figures, Images and Other Graphics

5.8 Use of External Hyperlinks

5.8 9 Redundancy

5.9 10 Subsection Guidelines

5.10 11 Annexes

6 HTML Markup

7 Artifact Identification

7.1 Structured Sort Names

7.2 Artifact Codes

8 Graphics

9 Document Structure

9.1 Introduction

9.1.1 General Principles

9.2 Title, Authors and Copyright Notice

9.2.1 Required

9.2.2 Recommended

9.2.3 Best Practices

9.3 Preface and Table of Contents Section

9.3.1 Required

9.3.2 Recommended

9.3.3 Best Practices

9.4 Overview Section

9.4.1 Required

9.4.2 Recommended

9.4.3 Best Practices

10 Content Domains

10.1 Introduction

10.1.1 General Principles

10.1.2 Publication Section Indexes

10.2 Domain Message Information Models (DMIM)

10.2.1 Required

10.2.2 Recommended

10.2.3 Best Practice

10.3 Storyboards

10.3.1 Required

10.3.2 Recommended

10.3.3 Best Practice

10.4 Application Roles

10.4.1 Required

10.4.2 Recommended

10.4.3 Best Practices

10.5 Trigger Events

10.5.1 Required

10.5.2 Recommended

10.5.3 Best Practice

10.6 Refined Message Information Models (RMIM)

10.6.1 Required

10.6.2 Recommended

10.6.3 Best Practices

10.7 Hierarchical Message Descriptions

10.7.1 Required

10.7.2 Recommended

10.7.3 Best Practices

10.8 Interactions

10.8.1 Required

10.8.2 Recommended

10.8.3 Best Practice

11 Common Domains

11.1 Common Message Element Types (CMETs)

11.2 Shared Messages

11.3 ClinicalStatementPattern

11.4 Messaging Infrastructure

11.4.1 Wrappers

12 Supporting Documents

12.1 Foundation Documents

12.1.1 Reference Information Model

12.1.2 Data Types Abstract

12.1.3 Vocabulary

12.1.4 Refinement, Constraint and Localization

12.1.5 GELLO

12.2 Background Documents

12.2.1 Version 3 Guide

12.2.2 Glossary

12.2.3 Methodology

Appendices

A Publishing Tools

A.1 Installation

B Templates and Building Blocks

B.1 Graphic Templates

B.2 Content Templates

C HL7 Mailing Lists

C.1 Editors List

C.2 Tooling Committee's Mailing List

D Storyboard Names

D.1 New Storyboard Names

D.2 Patients

D.3 Healthcare Staff

D.4 Organizations

D.5 Facilities

E Section, Subsection and Domain Codes

F Artifact Codes

G Document Codes

H Realm Codes

I Publication Process and Checklist

J Adding Annexes to Topics in a Domain

J.1 Identification

J.2 Using <div/> tags to structure an Annex

K Managing Components

K.1 Managing a large number of GIF files

K.2 Managing a large amount of storyboard content over many topics

Preface

i Notes to Readers

The Publishing Facilitator's Guide is intended to assist the Publishing Facilitator in creating and maintaining correct and consistent HL7 Version 3 Standards. It is also intended to assist balloters by providing rules for required and recommended elements within an HL7 Version 3 Standard.

This document is part of our ongoing effort to create more "background documentation" and was first published in September 2005 in conjunction with the HL7 Development Framework (HDF) and the Version 3 Substantivity Guide.

It also contains some elements of a "V3 Style Guide." Content creators are encouraged to follow the rules and guidelines that are contained in this document. Balloters may refer to this document when requesting that documents be changed to "follow the rules."

ii Acknowledgements

Many members of the HL7 community proofed early drafts of this document and provided valuable feedback.

This document was created in response to Dick Harding's request to "bring back the style guide."

The Publishing Committee would like to thank Dick Harding, Lloyd McKenzie, Joann Larson, June Rosploch, Ken McCaslin and Alexis Grassie for comments and suggestions on early drafts.

iii Changes from Previous Release

This is document has been updated from the original that was published in September 2005 based on ballot comments. We have added a section on References. The Style Guide for Narrative Content has been expanded significantly. The appendixStoryboard Names has also been updated with new cast members and an outline of the process for adding to the list.

Typos and other minor corrections were also made. The text was updated to conform to the Style Guide for Narrative Content.

iv Known Issues & Planned Changes

This is a draft. We are looking for comments, feedback and additional examples.

1 Overview

1.1 Introduction and Scope

The HL7 Version 3 Standards are a collection of related standards built upon a common Reference Information Model. Due to the extensive range of standards the development of consistent content and presentation can become a complex task. The HL7 Modeling & Methodology Committee has produced the HL7 Development Framework to guide the technical development of the standards. The HL7 Tooling Committee is mandated with developing appropriate tooling to support this methodology. The HL7 Publishing Committee is responsible for developing a presentation of the Version 3 standards that is a consistent, easy to use format that is appropriate for a variety of audiences.

This document presents an overview of the Publishing Process, the tools that are used to create the content, and some guidance on creating consistent and correct content. The goal of this document is to provide the information needed to create a consistent Version 3 Standard that conforms to the M&M methodology and uses the appropriate tooling.

2 Roles and Responsibilities

2.1 Publishing Committee Leadership

The Publishing Committee is an HL7 Board appointed committee and as such the leadership of the committee is appointed by the chair of the HL7 Board of Directors. The committee co-chairs are changed or reconfirmed whenever the HL7 Chair is changed.

The role of the Publishing Committee Co-chair(s) are as follows:

  • Chair conference calls and meetings.
  • Liaison with HL7 Board, TSC, International Affiliate Realms and other committees as necessary to represent the HL7 Publishing Committee and provide updates as appropriate.
  • Ensure that appropriate HL7 policies and procedures are followed by the committee.
  • Guide the activities of the Publications Technical Manager in accordance with his role and responsibilities.

2.2 Publishing Facilitators

The Publishing Facilitator is a person responsible for the submission of content to the HL7 Publishing committee to be published on behalf of a committee or realm.

All HL7 groups (Technical Committee (TC), Special Interest Group (SIG), Realms, Focus Group or Project) that are in the process of developing content that will be submitted for consideration as an HL7 standard must select a Publishing Facilitator. The selection process is governed by the group's processes (for example elected or appointed).

For the purposes of simplicity in this document we will refer to the group for which the facilitator acts the "TC" recognizing that it may in fact be any of the above mentioned types of groups.

Although the focus of this document is for Version 3 standards it should be noted that a Publishing Facilitator should also be assigned for management of the Version 2 standards and this may be the same person at the discretion of the TC. The traditional term "Editor" was determined to be inadequate, as it did not represent the full range of activities and responsibilities expected of this role; consequently the Publishing Committee felt that creating another term would encompass these expanded responsibilities.

The role of a Publishing Facilitator includes the following:

  • Participating as a member of the TC for which he is acting. Informing the TC of any issues, questions or decisions from the Publishing Committee that may affect the group.
  • Participating in the Publishing Committee conference calls and meetings whenever possible. Informing the Publishing Committee of any issues, questions or decisions from the represented TC relevant to publishing.
  • Ensuring that the TC is aware of any schedules or deadlines from Publishing.
  • Ensuring that a Ballot Request for Information Form is submitted to HL7 HQ by the deadline as is required for content to be included in a Ballot Cycle.
  • Ensuring that the TC's content is submitted to Publishing in the correct format, using the correct tooling by the required schedule to meet the publishing deadlines.
  • Ensuring that the TC's content is represented correctly and completely during testing (Preview) and that any revisions are submitted appropriately.

Note that although it is the responsibility of the Publishing Facilitator to ensure the above items, it is not necessarily his responsibility to perform all these tasks himself. The division of tasks within a TC is the responsibility of the TC's leadership.

2.3 Technical Publications Manager

HL7 HQ employs a Technical Publications Manager (TPM) who is responsible for supporting the HL7 Publishing Committee's activities. This role provides a consistent point of contact for all publishing related queries and support for the Publishing Facilitators and other HL7 members working on the development of HL7 standards.

The role of the Technical Publications Manager includes the following:

  • Attending HL7 Publishing Committee meetings and conference calls
  • Receiving content from the TC's for consideration to be published by the Publishing Committee.
  • Responding to HL7 Member queries regarding Publishing Committee activities or directing these queries to the Publishing committee co-chairs as appropriate.
  • Supporting Publishing Facilitators in the conversion of content to Publishing approved formats or in performing Quality Assurance as requested by the Publishing Committee co-chairs.
  • Other activities in support of the publishing Committee as requested by the co-chairs or HL7 Leadership.

3 Publishing Schedule

The HL7 content developed must undergo balloting prior to approval as HL7 standards. The process of publishing the documents and voting on them is known as a Ballot Cycle. Currently the Publishing Committee schedules ballot cycles prior to each Working Group Meeting (WGM). The results of a Ballot Cycle are discussed at the next WGM; consequently the ballot cycle is named for the year and month when the next WGM occurs. For example, the 2005Sep Ballot Cycle opened on August 1 and closed on September 3, and the WGM ran from September 11-16.

The Publishing Schedule is defined by the Publishing Committee each year and then presented to the Technical Steering Committee (TSC) at the Plenary Working Group Meeting for approval. The Publishing Schedule becomes official after the TSC accepts it. The current Publishing Schedule can be found on the HL7 Website on the Publishing Committee's webpage. Any TC may opt in or out of any ballot cycle. There is NO requirement to ballot a document in every cycle if resources are not available or if the content is not ready to be submitted for another round of balloting. If a TC decides to opt-out of a ballot cycle they may request one of the following:

  1. Content from the previous cycle be re-presented with no changes. A note will be added to indicate that the content is not open for balloting and is only being displayed to show the last balloted material. Any comments received on this material may be processed by the committee according to their internal processes and are not subject to the normal ballot reconciliation rules.
  2. The current work in progress may be presented with a note indicating that that the material is for comment only to show the current working direction of the TC. Any comments received on this material may be processed by the committee according to their internal processes and are not subject to the normal ballot reconciliation rules.
  3. The content may be removed completely from the ballot cycle. This is not available for any documents upon which other documents are reliant or may reference (e.g. Shared Messages). This strategy is not always recommended as it triggers questions about where the material may have gone.

The Publishing Schedule outlines deadline dates of the Publishing Process which must be met in order to publish and ballot the content. The deadlines are designed to ensure a high quality of balloted material and unnecessary negative votes are avoided. The schedule includes a two-week testing/preview period and a five-day window for ballot package preparation. Some of the critical deadlines on the Publishing Schedule include:

  • Ballot Announcement
    A Ballot Announcement must be sent to the membership 30 days before a ballot cycle opens. Any documents that are to be included in the ballot cycle must be a part of this announcement; since this is an ANSI and HL7 requirement no exceptions will be made. It is the responsibility of the Publishing Facilitator to ensure that the TC co-chairs return a completed Ballot Request for Information Form to the Project Management website in order to be included in a Ballot Cycle. Please note that the HL7 Policy on Ballot Reconcilations requires that all TCs and SIGs properly complete the reconciliation and negative voter notification requirements before they can re-ballot their domain content.
  • Ballot Preview and Testing Period
    The Ballot Preview and Testing period is a two week window prior to the ballot cycle opening that provides an opportunity to look at the content on the Ballot Preview Site before the Ballot Cycle officially opens. During the Ballot Preview Period, the Publishing Facilitator, and other TC members, should review the content to ensure that it is complete and ready to be voted upon. Any errors or omissions should be identified and either corrected by the Publishing Facilitator or brought to the attention of the Publishing Committee prior to ballot cycle opening. During the preview period the Publishing Committee will commit to updating the preview site with corrections within 48 hours of receiving the corrected content (usually sooner).
  • Content Deadline
    The Final Content Deadline is usually set to seven days before the Ballot Cycle is scheduled to open. This is the deadline for any content to be submitted to the Technical Publishing Manager if it is to be included in the ballot cycle. The Publishing Committee has allocated a full week between the content deadline before the ballot cycle open date because it is necessary to use this time to build the ballot website. In addition, the Publishing Committee reserves the right to establish interim content deadlines to aid the construction of the preview web site and coordinate cross-domain publishing. Any content not received by the published final content deadline will not be included in the ballot cycle with the following exception: If a preview of the content has been received and processed AND permission is requested and granted based on extreme special circumstances an extension may be considered. Examples of extreme circumstances include unexpected tooling problems or the publishing facilitator being hit by a bus.
  • Ballot Cycle Open
    The Ballot Cycle Open and Close dates are the bookends to the Ballot Cycle. During the time between the Open and Close dates, the Ballot Cycle is referred to as being Open. This means that HL7 members (and paying non-members) will be reviewing and voting upon the content.
    There is generally at least a one week period between the closing of a Ballot Cycle and the following Working Group Meeting. This week is reserved to allow for the tabulation of the votes and organization of the reconciliation meetings during the WGM. The intent is that the TC discuss the votes and comments received during the ballot cycle on its content at the Working Group Meeting.

Refer to the HL7 Ballot Desktop documentation for more information on Balloting.

4 Reference Documents

The authority for style and grammar rules in HL7 publications is the Chicago Manual of Style (CMS). Any exceptions to the CMS will be noted.

The authority for spelling and meaning is the Webster's Third New International Dictionary, Unabridged.

The authority for spelling and meaning of new, technical terms, not present in Webster's, is a documented use of the term in any of the following documents, in order:

  1. an Institute of Electrical and Electronics Engineers (IEEE) standard
  2. an Internet Engineering Task Force (IETF) standard
  3. the Word Wide Web Consortium (W3C) Glossary
  4. an ISO Standard, or
  5. an ANSI standard

The authority for spelling and meaning of medical or other healthcare terms is National Library of Medicine Medline Plus Dictionary. An example of such a word is pharmacogenomics, which would not be in a "normal" dictionary, but is a valid medical term.

HL7 is not in the business of coining new words. If a need is found, the new word is to be submitted to the Publishing Committee for approval. Newly coined words must appear in the glossary.

5 Style Guide for Narrative Content

Narrative content within the HL7 standard SHALL be consistent from one document to another and professionally presented. To attain this objective, the Publishing Committee, based on comments received during the balloting process and committee review, has established the rules and conventions set forth in this section. Relevant material from the v2 Style Guide has also been brought forward.

This section is to be used in conjunction with the HL7 Development Framework.

5.1 Language

HL7 publications are written in formal American English.

Note the following characteristics of formal American English:

  • Complete sentences with proper and complete punctuation SHALL be used rather than sentence fragments. An exception to this is a list where fragments may be used.
  • Contractions SHALL NOT be used
  • Colloquial expressions SHOULD NOT be used
  • Acronyms MAY be used provided the initial entry within any published domain or topic specifies the full name of the entity followed by the acronym in parenthesis (see 1st preference in CMS, Section 15). If the acronym is defined in the HL7 Glossary, a hyperlink MAY be provided.

5.1.1 Use of SHALL, SHOULD and Other Modal Verbs

This section describes the terminology for expressing the stringency of a conformance statement.

HL7 adheres to ISO/IEC directive, Appendix G, as delineated in the following table:

Table 1: Stringent Use of SHALL, SHOULD and Other Modal Verbs
To Convey the Sense of: / Use the Following:
Required/Mandatory / SHALL / SHALL NOT
Best Practice/Recommendation / SHOULD / SHOULD NOT
Acceptable/Permitted / MAY / NEED NOT

Examples: