Tuesday, January 8, 2013

What were we trying to do?

Wes Rishel recently posted about an ongoing discussion on the HL7 Structured Documents list.  Another discussion is also cropping up about particular wording ("such that it") used in the C-CDA specification.  And then there's the discussion about what the intent was for the C-CDA (and former CCD and C32 content) about the results organizer.

All of this stems from one challenge, which is how we incorporate requirements (or fail to in most cases) into the specifications.  The specifications tell you what to do, but in many cases, not why.  The why is very important to implementers because it explains the reason it is the way it is, rather than some other way, and provides further implementation guidance about the intent behind each template or structure.

Most HL7 V3 specifications include story boards (examples of use cases really), but CDA implementation guides usually don't because they are still written in Word.  Even so, V3 story boards are often rather incomplete with respect to details.

Some of these challenges are a result of tight deadlines.  All too often, we've been rushed to get something done because of various deadlines that aren't under our control.  It takes longer to write something that explains the rationale behind the specification in addition to writing the specification.

I've pushed for both rationale and examples (see rules 15 and 16 here), but the tooling we have today (in HL7) doesn't support either yet directly.  Back in HITSP I insisted that value sets and data elements had more than just a name.  They had to have at least a sentence defining them.  I think the same should be true for every constraint.  If we can't write a sentence explaining why it is there, then perhaps we shouldn't have it.

One of my hopes is that the ballot quality committee newly formed in the HL7 Publication workgroup will take up some of these issues to make this content easier to read.

This isn't just a problem that is experienced in Healthcare Standards.  It's fairly common in other complex standards.  One of the "bibles" used by many in the structured documentation world is Charles Goldfarb's The SGML Handbook.  That book includes the entire text of the SMGL Standards (ISO 8879), extensively annotated. Michael Kay's various books on XSLT are similarly valuable (I own XSLT 2nd Edition).  I hardly every try to do any serious HTML programming without dragging down my copy of O'Reilly's Flamingo book, Dynamic HTML, by Danny Goodman.  All of these books on my shelf have extensive tabs, post-it notes, and corner turn-downs marking important sections.  Each of them is rather large (600+, 900+ and 1300+ pages respectively).  Even though I've read SGML, XSLT, HTML and CSS standards directly, these books are my primary sources.

When I wrote The CDA™ Book, those books were how I aspired it would be used, but I could barely manage 300 pages in the year I spent on it.   While I might readily generate more than 500 pages annotating the Consolidated CDA Specification, I don't have the time (or funding) to do so, nor do many others involved in development of these specifications.  The tooling challenge has a similar issue.   I don't know exactly how to solve this problem, but I do know that it is one that needs to be solved.  Like everything else, one key ingredient to the solution will be time.



  1. Interesting post, Keith. As a consumer of the sorts of documents you are involved in creating, one thing I would strongly suggest is to clearly differentiate requirements, on the one hand, from the "guidance about the intent behind each template or structure" which you propose providing more of. While the latter can be very useful, it can create confusion when it isn't clear whether or not it is expressing a new requirement.

  2. >> "It takes longer to write something that explains the rationale behind the specification.."


    One thing that troubles me is that much of what should and would be written by way of explanation is trapped in protracted discussions that take place on HL7 lists -- sometimes over months and years.

    And to make things worse, this information is more often than not existing in a much less digestible and useful form than would be directly usable in a standards document, so it would need to be heavily "post processed" and edited as well as discovered.


  3. Thomas,

    There's no substitute for active participation that I've ever encountered. Even recording everything that was said doesn't do it. You simply cannot distill active participation in T-cons and face-to-face meetings in a way that will make non-active participants be able to understand the full discussion. That is why it is important to participate.

    Having said that, we definitely need to make the outcomes and decisions resulting from those discussions on the specifications digestible, either as requirements, or as Eric states, intentions, when we produce the specification, and those need to be included in the specification.