Guidance for FHIR IG Creation
0.1.0 - CI Build

Guidance for FHIR IG Creation, published by HL7 International - FHIR Management Group. This is not an authorized publication; it is the continuous build for version 0.1.0). This version is based on the current content of https://github.com/FHIR/ig-guidance/ and changes regularly. See the Directory of published versions

IG Home Page

Introduction

Implementation guides are the mechanism that FHIR uses to explain how to use the FHIR specification to achieve interoperability in a particular space. They use a variety of FHIR resource to express that guidance computably and then allow those artifacts to be converted into a rendered form (typically as a web site) for easy understanding by software developers and others.

Implementation guides can be written by anyone and a wide variety of tooling can be used to both define and publish such guides. This implementation guide is an 'example' that shows how to use HL7-defined tools and templates to author and then render implementation guide content. It also provides recommended practices for IG authoring, including suggestions around the organization of the implementation guide, how artifacts should be named and how content should be presented to maximize the usefulness of the guide for its target community.

The documentation in this implementation guide is a work in progress. The tooling used to support implementation guide creation and publication continues to change. As well, the community continues to learn more about what constitutes "best practice" around implementation guide design and the documentation here will evolve to reflect any changes in guidance.

Technical details

This implementation guide specifically documents the HL7 IGPublisher tool, the most recent version of which can be found here. It applies to all IGs that make use of HL7's IG base template. This currently includes the following:

Template id Github repository Description
fhir.base.template https://github.com/HL7/ig-template-base This template includes all of the scripts, layouts, etc. to produce an HL7-style implementation guide. However, it does not include the HL7 or FHIR logos. It is intended to serve as a base for most non-HL7 IG publication
hl7.base.template https://github.com/HL7/ig-template-hl7 This template inherits from the fhir.base.template and adds in the HL7 logo, a generic HL7 color scheme and some HL7-specific rules.
hl7.fhir.template https://github.com/HL7/ig-template-fhir This template inherits from the hl7.base.template and adds in the FHIR product family logo and color scheme.
hl7.davinci.template https://github.com/HL7/ig-template-davinci This template inherits from the hl7.fhir.template and adds in the Da Vinci logo and some boiler-plate Da Vinci-specific text
hl7.cda.template https://github.com/HL7/ig-template-cda This template inherits from the hl7.base.template and adds in the CDA product family logo and color scheme.

This implementation guide includes the following sections:

  • Background: Pointers to various training material about FHIR, profiling and implementation guide development that should be understood as a pre-requisite to developing implementation guides using this template
  • IG Tooling: An exploration of the different tools available for authoring the different resource types used in FHIR
  • Using IG Templates: Instructions describing the files and file structures to be used when creating implementation guides using this template
  • IG best practices: Recommendations for creating implementation guides that are easy to understand and use.
  • Extending the HL7 IG Templates: Guidance on defining project-specific templates that leverage the capabilities defined in this template
  • Downloads & Support: Allows download of this IG and provides links to other related/support materials for IG creation