A Perfect Implementation Guide

On the HL7/IHE/ONC Consolidation Project call last week, two of us agreed to start a separate workgroup to discuss publication format.  This post is my first "deliverable" for that workgroup.

I've worked on CDA Implementation Guides from HL7, IHE, and HITSP, and have seen guides from CMS, France, epSOS, Germany and Japan.  I've also written a book on CDA due out later this year.  In my experience, each of these has something to contribute.  Let me lay out a list of requirements for the perfect guide:

1. In order to adjudicate issues, there must be single "normative" publication format which is the official specification.
2. A richly linked, searchable multimedia format must be available to enable implementors to quickly locate needed information.  
3. A printable format containing all content and containing a table of contents with page numbers must also be available to enable implementors access to a printed format to enable access.
4. Auxiliary materials, including sample files, conformance data, schema, Schematron, UML models, et cetera, must be supplied with all delivery formats to further support implementation.
5. Auxiliary materials will be supplied in standards based formats to support use with off-the-shelf tools.  For example, XSD, Schematron, or XMI files.  
6. Tabular data will be made available in either CSV or XML formats to enable easy import into off-the-shelf products.
7. XML formats used to convey tabular data must be well documented, preferable standard formats, and should be easy to use with off-the-shelf products (MIF doesn't count).
8. Publication formats must be downloadable in their entirety without need for outside web services or network connectivity to enable disconnected access.
9. The Implementation Guide must have testable conformance criteria to ensure conformance.  NOTE:  Testable does not imply that ALL tests can be automated.
10. Conformance criteria must be expressed in a computable form, and made available as data/models to enable other systems to use the information in innovative ways.
11. Conformance criteria will be divided into two sets, schema validation, and functional validation to support input validation and functional testing as separate capabilities.
12. "Schema" validation criteria will identify invalid document exchanges without requiring any specific knowledge of inputs.  A document that is not "schema" valid is not a communication conforming to the implementation guide.
13. Functional validation criteria will identify specific requirements or capabilities required of document creators and document receivers (what IHE calls the content creator and content consumer actors in its profiles).
14. Conformance criteria will generally be organized in the order in which information usually appears in the documents exchanged for ease of access.
15. Conformance rules will provide an explanation of the purpose of the requirement to help implementors understand what the rules are trying to accomplish.
16. Conformance rules must provide examples of conforming results, and should provide examples of non-conforming content when that will aid implementation.  
17. The guide will use readily understandable terms and methods, or when domain specific terms or methods are used, will explain the domain specific content to enable implementors who are not familiar with the domain (e.g., HL7 V3 Modelling) to understand what is being said.
18. The guide will provide necessary information in multiple forms:  UML models of conforming content, conformance statements in english prose, and where possible, in tabular form to enable access via a broad variety of learning styles, as well as examples of conforming content.
19. Only one form of presentation will be normative, others will be informative, to ensure that conflicts between representations can be adjudicated.
20. Automated solutions will be used to generate the multiple representations, to ensure consistency of information in the guide.