What belongs in an implementation guide? Many HL7 implementation guides and IHE profiles include the requirements of an implementation, sometimes with an explanation of the more tricky bits. On a discussion today, someone asked (or at least I thought they did) about the separation of content between documentation stuff and functional requirements with respect to the template meta-Model.
I responded thus:
It's like code. When I'm doing a code review, if a comment in the code is wrong, the code is wrong, even if the comment doesn't functionally contribute to the execution. That's because it does contribute to the maintenance of the code it comments on. So, I don't see a need to keep them separate, and I do in fact see a need to keep descriptive, "non-normative" stuff together with the stuff that allows systems to validate or implement the templates.
The point being that the "non-normative" stuff is what helps implementers do stuff, and it needs to be kept together, even if it doesn't help in code generation.
I agree, Keith. The examples or lack thereof greatly affect the usability of an implementation guide, and thus the time to develop the solution. I, and our developers, definitely appreciate the "non-normative" XML snippets and other examples included in IGs. Of course, as you say, those "comments" need to be correct, otherwise someone will go off on a tangent.
ReplyDelete