The FHIR Specification is a base platform specification - it creates the structures and capabilities that are used across the entire FHIR eco-system. In principle, it would be good if everyone agreed about everything, and we could have just one single specification, but there is no such agreement. In addition, such specification would be very large and there would be unresolvable life-cycle contention about how often to update it.
In order to manage these issues, the FHIR community publishes Implementation Guides that build on the specification and detail how FHIR is used in a particular context.
An implementation guide is a combination of human readable documentation and computer processable content published as a FHIR NPM package. By convention, the human readable documentation is published as a set of html pages to a website that is public or private, but this is not necessary (though it is strongly recommended).
How to Author Implementation Guides
In practice, authoring implementation guides requires tooling support. Any tool that produces a human readable output and a conferment NPM package can be used. Here's a list of the known tools:
|HL7 IG Publisher||https://github.com/HL7/fhir-ig-publisher|
This is a command line tool that takes a set of file inputs (resources, markdown, other kinds of content) and generates the output. This tool has a strong focus on generating correct validated output, and is also used in the back-end of some of the other tools. Much of the documentation on this web site relates to it's use.
For further information, see documentation
|SUSHI (FHIR Shorthand compiler)||https://github.com/FHIR/sushi|
This is another command line tool that converts FHIR Shorthand (FSH) to a set of inputs ready for the HL7 IG Publisher to process. Authors may rely on the HL7 IG Publisher to run SUSHI for them at the start of the generation process.
For further information, see documentation.
This is a web-based collaboration platform to create, manage and publish FHIR implementation guides and specifications. It operates under a freemium model, with the first FHIR modeling project being free.
Again, any tool can be used, but HL7 requires that implementation guides published by HL7 itself be produced by a tool that uses the HL7 IG publisher for the actual generation process.
Documentation to help Authors
HL7 has a Guidance Implementation Guide that provides specific guidance on best practices around IG creation as well as information about some of the tooling extensions and capabilities relevant to creation and publication of implementation guides. Note that this documentation mixes general documentation about the design of implementation guides with tooling specific advice based on the HL7 IG publisher