My Favorite Tools for Building FHIR Implementation Guides for IHE and HL7

I've been doing a lot of implementation guide development lately, and have some favorite tools that I'm starting to work with.  Here's a look at what I've been using.

Source Code

The first of these is a source code repository.  I've been using GIT for source control, and github.com as a free repository for IG development.  You can look at two of the guides I've developed at github.com/IHE/ACDC and github.com/HL7/fhir-project-mhealth to see two of the projects I've built using this toolset.

Editing Content

I like writing content in something simple.  A long time ago I prototyped a process for IHE whereby we created IHE Profile content on the IHE Wiki.  Wikitext in MediaWiki is nearly the same as Markdown.  The value of using something like this is that it allows contributors to focus more on content and less on formatting or making things pretty.  Pretty is good, but that should be the purview of a single person with appropriate design skills rather than a dozen volunteer editors.

Text Content

So, these days, I'm using a the fairly simple Markdown editor provided in Eclipse (more on that later).  There are plenty of Markdown editors you can use, many which work in Eclipse.  I also use FluentMark from time to time.  My favorite XML Editor also supports JSon and Markdown content.

One of the challenges that contributors often have with Markdown is that it's really not very user friendly for editing and creating content pages.  Confluence or other Wiki style pages are a good place to enable not technical users to create content.  Unfortunately, they don't integrate well with source code control systems.  I'm going to look into some solutions whereby we can get some good content editing that integrates into git-based solutions.

Image Content

My biggest used for image content is with structured images, for example UML Use Case, Sequence and Class diagrams.  My goto editor for this material is PlantUML.  PlantUml has an Eclipse plugin that allows you to view UML diagrams within Eclipse while you edit the diagram in a text editor.  You can also run PlantUml from the command line to automate the process of image conversion.  This makes it really useful in automated builds.

XML and JSon Content

I'm really happy with Oxygen XML Editor for editing structured content like XML and JSON documents.  Happily, it also supports Markdown so I can use it for that too.  It has some features that are helpful for finding invalid Unicode characters, something that shows up frequently when you copy and paste text from Word into your markdown documents.

Converting from Microsoft Word or Other Formats

For those that have a lot of content already in Microsoft Word or PDF or other formats, PanDoc is an excellent open source tool for converting content between these formats and Markdown.  PanDoc supports a number of flavors of Markdown, including CommonMark which is the format used by the HL7 Implementation Guide Builder.

FHIR Profiles and Instances

There are a number of different tools that support building FHIR Profiles and instances.  The original FHIR specification build tools allow you to specify profile content in Microsoft Excel, but that's pretty complex tool chain for most user's.  Today, I'm using SUSHI which compiles FHIR Shorthand into Profiles and example instances.  This is an open source tool developed by an award winning team of people over at Mitre.  While still very much a work in progress, it's already saved me a tremendous amount of time, and the Mitre team has been very responsive.

Build Environment

Integrated Development Environment

These days I use Eclipse as my integrated development environment.  I'd love to figure out a way to make of the editing capabilities available using something like Confluence and provide some automated conversions so that when you create or update a content page, you have an easy way to edit the sub-components it requires (e.g., other content pages in links, or images or example content).

Build Automation

Right now my build environment is very much command line and batch file driven.  What I'd like to do is turn it into a Maven project with dependencies on the various editing and other tools described above.  That way I could build a template project which would automate the build of the IG Content.

IG Builder

I use HL7's IG Builder tool to generate an implementation guide.  Between that and github, it automatically deploys my draft IG to http://build.fhir.org/ whenever I commit something.  However, I like to do a local build to confirm that I'm going to get what I want, and it takes less time to test things out that way.

To perform a local build, I also need to install Jekyll, and to use that I need Ruby.

Putting it All Together

To put this all together, what I'd love to see is an installer that would:

1. Install or use an existing Java VM
2. Install or use an existing set of Git Tools
3. Install or use an existing set of Maven Tools
4. Install or use an existing Eclipse installation
5. Install PlantUML with Eclipse
6. Install or use an Node.js installation (required for Sushi)
7. Install or update the current version of Sushi
8. Install or use an existing Ruby installation.
9. Install or use the existing Ruby Dev Tools.
10. Install or use an existing Jekyll installation.
11. Provide an example projects with pre-constructed outlines following best practices for
1. HL7 FHIR Implementation Guides
2. IHE FHIR Implementation Guides / Profiles
3. IHE non-FHIR Profiles (to demonstrate that IG Builder can be used for these).
12. Provide example plantuml files for use cases, sequence diagrams, and actor / transaction diagrams that are often used in IHE profiles and could be used in other Implementation Guides.
13. Provide documentation for the whole package on how to use the various parts of it.