What if HL7 interface specifications were easy to document?

Some organizations call them HL7 conformance profiles, others call them HL7 interface specifications. They’re all talking about a description of the data format used for exchange between systems within a care facility.

The terminology might not be consistent, but the challenge is: documentation. How do you document conformance profiles so that the description is up-to-date and trustable?

3 HL7 Documentation Issues

1. Creation is Time Consuming

Documenting an HL7 specification requires a fair amount of effort. Applications exchanging data through the HL7 standard usually exchange several data elements. Each data element has its own definition and plays a role within your organization’s workflows. For instance, in HL7 v2.6, the PID (patient ID) segment contains 39 different fields; the PV1 (patient visit) segment contains 52. Each field contains several potential components and sub-components. Obviously, an interface analyst might not need to document them all. But analysts still need to invest several hours and days of work digging in there. Before coding an interface, they need a thorough understanding of how each data element interacts within each data flow, and they need to document it all.

2. Multiple Customers, Multiple Needs

Another fact that makes HL7 specification documentation challenging: different stakeholders might need the documentation for different purposes. For instance, the interface group would need it for daily internal work. A 3rd party vendor might need it to configure a new system installation. The vendor would probably need partial documentation limited to just a few data elements. In turn, you might want to limit sharing to just a few specific details per element. You could be looking at maintaining several documents containing slightly different information. That brings us to next point…

3. HL7 Documentation Is Hard to Maintain

Once you create the documentation, the cold hard fact is… you need to keep it up to date if it’s going to retain any value. Workflows change over time, and how your systems collaborate change as well. If anything, outdated and misleading documentation is worse than no documentation at all. But manually updating a pile of specifications with multiple flavors is a lot work.

HL7 Documentation Made Easier

Now, what can we do to avoid all this work and improve the overall quality of HL7 interface specifications? One solution is to centralize all conformance profile documentation in a single place – say, Excel. You then generate all your documents from a single source. That way, you update once, and pull reports as you need them. Excel filtering capabilities can be pretty useful here.

Obviously, Excel wouldn’t give you sophisticated formatting or document versioning. But this could be a first step towards better management of your organization’s valuable knowledge assets. The next steps would involve leveraging this new asset to improve processes and become more productive… but that’s another (big) discussion for another day 😉