Convert your FHIR JSON -> XML and back here. The CDA Book is sometimes listed for Kindle here and it is also SHIPPING from Amazon! See here for Errata.

Sunday, May 15, 2011

Explaining Why

One of the things I'm called to do pretty often is to explain why HL7, IHE or HItSP did something a certain way. Recently, when designing what I called A Perfect Implementation Guide, I added the explanations of why into the design of the guide.

OK, so Why should that be required?

You should be able to trace requirements of the standard back to requirements imposed by:
  • Requirements of the use case
  • Requirements for Interoperability (e.g., there may be multiple ways to do something that should be limited, such as exchanging intervals of time)
  • Requirements or limits of one or the other system involved (e.g., System X can only deal with two or fewer address lines).
  • Policy Requirements (e.g., Facility is required by law or regulation to be able to access this data).

Providing the why supports traceability to requirements. I've seen few standards projects actually trace back to requirements in any formal way.

DAMs and Domain Information Models are a good start. The DAM can (if done well) explain the requirements for a specific message element. Not all DAMs do that (DAMs that don't are damned to leave us scratching our heads).

Explaining why a data element is required helps the reader to develop an opinion that can be informed by the requirements. Leaving that out can leave the reader uncertain as the need for a particular datum. Explaining why an element is recommended or optional, and how it might be used by the receiving system may actually get more developers to use the recommended or optional data element, especially if the why is convincing.

It goes back to identifying our audience and dealing with them appropriately. The audience for a standard or implementation guide includes implementers and end users. Implementers are not always experts in the clinical context. End users are not always experts in the engineering need. Putting in the why can help either to see the need.

Expecting either to go back to a prior document to find the why is not realistic (unless you hyperlink it). We all have tight deadlines, are over-scheduled, and under-resourced. So, make it easy for me to understand WHY you put that there. DOn't assume that it's obvious. Believe it or not, as an implementer, I have very little formal clinical training, and there are many more like me in the same boat. Similarly, don't expect those reading your specifications that do have clinical training to have the engineering background to understand those details. Those that have both are rare, and they probably were in the meetings where the work was discussed.

Let's think about our audience, and start making it easier for them to implement, and giving them the why's that will begin to make them as expert as those who write these specifications.

Providing the why will do one more thing: It will free us up from having to remember why we did that, giving us more time to work on new things.