Implementation Guides vs. Specifications

We've been having one of those long running discussions over on the Structured Documents list-serve over the past couple weeks.  There are two parts to the eterna-thread, one on the need for more examples, and another for the need to simplify the documentation.  I've read the free manuals myself, and while I believe every engineer should do so at least once as well, I completely understand some of the challenges they have, because I have them too.

Recently, HL7 published Core Principles and Properties of V3 models, which includes about 30 pages of text on Coded Model elements.  This is a perfect example of where we need to simplify.  I've never had a developer ask me for this amount of detail. They've always asked me two questions, and sometimes a third:

1. What codes do I have to use?
2. What do I do if I cannot use them?
3. What do I do with the other codes I have?

This is the implementer viewpoint.  They don't want the theory, but rather the answers that theory provides.  What this really gets down to is the real difference between what an implementer would find useful as in an implementation guide, and what we in HL7 think is the value we are generating, which is the specification for what gets implemented.  If we were to apply a UX assessment to our documentation, we'd find they were sorely lacking.

For HL7 experts, the specification is what we need.  But for the rest of the world, the real value is in more than just the specification.  From a customer perspective, the ratio of "HL7 Experts" to HL7 users is probably 100:1 or even 1000:1 (where HL7 user = someone who has to look at a raw message or CDA document and do something with it in code or in an interface).  They need the explanations for how to handle common situations, for example, as in the cases described above.  It needs to be clean, crisp and simple.  It can reference the theory, or other documentation, but for the most part, it needs to tell people what they need to do.

There are several challenges with this level of documentation.  The biggest challenge is that it is repetitive, having the danger of nearly, but not correctly duplicating what already exists (we have that challenge today with SHALL/SHOULD and CWE/CNE), thus encouraging implementation behaviors that actually deviate from the standard.  This was the "HITSP" complaint, and given that we were writing quite a bit and basing it on other organizations standards, we definitely didn't want to duplicate what they had already produced.  It also had the challenge of requiring a cascade when the underlying standard changed.  While we cannot avoid that challenge today, we can do a lot better than we did 6 years ago.  We have a lot more tools to generate implementation guides, and to ensure that we follow the rules of the base standards (e.g., Trifolia and MDHT).  

The second biggest challenge is that it is "expensive" to produce.  And when the producers view themselves as the customers, the value to that extra step is negligible.  So, we need to change that viewpoint.  But to do that, we need the consumers of the documentation at the table.  And when they show up and start complaining, we need to listen to them.  We must recognize that the value of a standards organization is not in the number of specifications it produces, but rather in the number of implementations of those specifications.  If we produce thousands of specifications and nobody implements it, and another SDO produces one, but everyone wants to implement it, what will happen?  (Hint, we've seen that occur before).

As a person with a foot in both places, one as an expert at the table who has read all of the docs, and the other as a person trying to get implementations built with engineers that don't have the time to learn everything there is to learn about the theory of healthcare informatics, I am challenged.  I don't always recognize when there is a problem (keep me honest and keep complaining, eventually I do catch on).  At the same time, keep listening and participating.  The only way to EFFECTIVELY change an organization is from within.  When you become part of the organization, you also can improve it.