Thoughts on a canonical FHIR Implementation Guide Outline

I've been working on implementation guides for decades, first in CDA and then in FHIR, in HL7, IHE and other SDOs.  Everyone has  a slightly different approach, but there's also a lot of commonality.

Assuming a web publication format with highly linkable output, this is how I would put the outline together today:

Home

The home page orients you towards the entire specification.  It contains a short (no more than a paragraph) description of the problem it solves, and allows you to navigate through the main components of the specification. It includes at the end a link to download the specification or subcomponents of it used for implementation, a link to any source code or other materials, et cetera.

Intro

The introduction section describes the content of the IG in more detail.  This includes the audience for the material, the scope of work explicitly included and excluded, describes the conventions used in the document (e.g., key words such as SHALL/SHOULD/MAY, other conventions), describes the organization of the document in detail, and acknowledges contibutors and/or sponsors of the work.  If there's a short glossary, it can go in this section as well, a longer glossary goes at the end in an appendix.

Overview

The overview section gives a clear and detailed statement of the problem that the IG is trying to solve.  It includes an explanatory description of key concepts and terms which may not be familiar to all readers, but these are short (more detailed material can be included as references).  It can also provide a description of the technical environment in which the IG is expected to be used (e.g., what systems, networks, et cetera, are available/used).

Use Cases

The use cases section lists each high level use case (these are user oriented), provides a short description of each one, and then launches into a detailed description of each of the use cases.  The detailed descriptions include sequence diagrams associated with the steps of the use case, along with a narrative description of what happens in each step.

Actors

The actors section lists each technical (e.g., non-human or system) actor identified in the use cases, and specifically identifies the requirements of each of these.  If there's optional behavior for the actors, it can be described in this section.  I'd recommend identifying options by name, and giving requirements for each named option (this is how IHE handles options), as it makes addressing verifying implementations do what they say they will do (a.k.a., Conformity Assessment) a lot easier.

Security

There should be a security considerations section that addresses security concerns.  This section should identify all the security concerns, and may reference more detailed content elsewhere in the IG.  The security concerns section may identify specific actor requirements, but these should be detailed in the requirements for individual actors.  This is so that all requirements are present in one place, not spread throughout the IG.

Interactions

There should be a section to describe all the interactions the IG has between the technical actors it defined (IHE identifies these as transactions).  In a RESTful environment, these are the GET/PUT/POST/DELETE operations that it supports.  In FHIR, these are the operations that the IG describes.  This includes the standard ones such as read, vread, search, create and update, and others such as $expand, but also includes any custom operations described by the IG.

Detailed Interaction Descriptions

Each interaction should describe the requirements of the actors participating in the interaction, and should also include a security considerations section, which should indicate specific security requirements that can be tested during the execution of the interaction (e.g., audit logging, encryption, et cetera).  When the interactions work with profiled content, the requirements should indicate that the interaction shall operate on content that conforms to the specific profile.  That profile should be described in more detail in a separate section.  There are some occasions where a FHIR Resource profile is described in general form (e.g., uses this content), but have specific constraints in the content of some interaction (for example, when a resource is sent via create, it shall not have an id, but when sent for an update, it shall).  In this case, make these specific requirements of the interaction.  One can also create profiles specific to each interaction, but this should only be done when warranted by complexity.

Content Profiles

There should be a section that provides a high level description of each content profile (e.g., resources, extensions, value sets, coding systems, capability statements et cetera).  These should be organized in some way (e.g., by type), and described individually.  Best practice indicates that the resource or extension profile content should include at least some sort of introductory section describing the purpose and rationale.

Detailed Content Profile Descriptions

Each content profile (e.g., Resource, Extension, Value Set) should have not just the requirements, but also an explanation of why they exist (the rationale).  This will help to explain to readers why this item is required and what the purpose is behind its inclusion.

Examples

The examples section (or appendix) provides examples of conforming interactions and content.  One include examples with each interaction and content.  The examples section simply aggregates these these and provides a high level description of each example.

I've been working on a few examples of this.  You can see what I did for the IHE ACDC Profile and the HL7 mHealth App Data Exchange IG on the web.

I'm not perfect, and I haven't managed to hit on all of the above in either profile.  You can also see I have experimented with slightly different organizations of each as well.  I'm working towards the idea that there should be one generalized approach though, and I can see where I might be able to put together a pretty decent outline for use by either IHE or HL7 for use with the FHIR IG Builder.

   Keith

P.S.  While the work I'm doing here is strictly related to FHIR, there's a notion that this could be applied more broadly that would enable this and my earlier post this week for other structured formats such as CDA, HL7 Version 2, even X12 and NCPDP wire formats.  I'll talk about this a little bit later.