In a previous article we introduced the concept of FHIR implementation guides. Recently our FHIR team at Firely had another in-depth discussion about this topic. In this follow up I’d like to share some more details concerning the concept architecture of implementation guides.
An implementation guide contains a set of documentation pages. Let’s explore these two concepts in further detail.
- Provide a set of conceptually related documentation content
- Via a list of references to Documentation Pages
- Describe resources defined by one or more conformance packages
- Define the content navigation structure
- Given a specific documentation page, specify the list of child pages
- Given a specific documentation page, specify a list of related pages (“see also”)
- Define the common presentation template
- Define the common page layout
- Define common visual styles
- Define navigation controls (e.g. main menu, navigation bar, links to children etc.)
- Possible representations (not defined yet)
- A directory structure with files
- A ZIP file
- A composition resource providing references to included resources
- A stand-alone resource, addressable via URL
- Initial implementation could use a resource profile based on Basic resource
- Possible candidate for promotion to a standard resource
- Shared/reusable; may be included in zero, one or several implementation guides
- Example: an implementation guide for a hospital may include documentation pages published by a national organization.
- Contains editorial content
- Structured content (HTML; markdown)
- Basic formatting; must be suitable for display in differently styled implementation guides
- Define page topic via a resource reference
- Allows searching for documentation pages concerning a specific resource
- Optionally provide references to local page resources such as images
- Optionally provide references to related external information, e.g. YouTube, HL7 etc.
- Does NOT provide references to other Documentation Pages
- Implementation Guide defines navigation structure
Sharing common documentation pages
A specific documentation page may be included in one ore more implementation guides. For example, a hospital implements resources defined by a national organization. The implementation guide for the hospital includes the relevant documentation pages from the national implementation guide. This implies that a documentation page itself has no navigation context; the navigation structure must be defined by the implementation guide. Specifically, an implementation guide defines the list of child pages for a specific documentation page. Different implementation guides can include a common documentation page in different positions within the navigation hierarchy.
Publishing documentation pages
A documentation page can express the topic of the page via a resource reference. This provides documentation search capabilities for FHIR servers; given a specific resource, a server can resolve the associated documentation pages. For example, a FHIR registry could present a list of links to related documentation pages on the detail page for a specific resource. However because an individual documentation page does not have a navigation context, the server can only present a stand alone, bare rendering of a documentation page. A user must visit the associated implementation guide(s) in order to navigate to related documentation pages.
Implementation guides and documentation pages will be published to a FHIR registry server. A FHIR registry server could provide:
- List / search conformance packages
- Detail page for a conformance package can present links to related implementation guides
- List / search implementation guides
- Hyperlink to an implementation guide leads to the start page, as defined by the implementation guide author
- List / search documentation pages
- Less useful, because stand-alone pages have no navigation context
- Optionally the server could present a list of associated implementation guides that include/reference a specific documentation page