Did your parents ever ask you that question when you were young? Usually in an exasperated voice because you had done something (that at least they thought was) stupid. In my family, we have at least two usual responses to that: "Thinking? What makes you think I was thinking." That's an admission that yes, it was a stupid thing to do. The other response is "It seemed like a good idea at the time." That response usually means that we had a good reason for doing what we did, or at least we thought we did. Often though, the reason itself is lost to the recesses of memory. Sometimes there's an important nuance that occasionally returned to us later that reminds us why this is actually a good idea.
Recently, in working through the BPMN appendix for IHE PCC, I've started to write down why I think something is required or recommended. I've talked about this before (in What were we trying to do?). For every requirement I've been trying to provide at least a one sentence explanation for the requirement. Sometimes it's obvious: (e.g., Of course you want to give this a name), and I struggle to write the explanation of the obvious, but do it anyway. Sometimes what I think is obvious isn't, at least to someone who is encountering this stuff for the first time. Other times, it isn't so obvious why you need such a thing, or why you chose that way to do it. In these cases, I can really see where this adds value, and not just for other readers. Already I have 20 or so pages of text, and I'm going back through it about every other day. Those little notes are gold when I get to something I wrote a few weeks back and am trying to recall why I did that. Here's an example:
As we work on standards, I'd love to see more of this sort of explanatory text in both HL7 and IHE specifications. It might make ballot reconciliation or public comment and post publication maintenance a lot easier. It should certainly make implementation easier for the end users of these specifications.
Recently, in working through the BPMN appendix for IHE PCC, I've started to write down why I think something is required or recommended. I've talked about this before (in What were we trying to do?). For every requirement I've been trying to provide at least a one sentence explanation for the requirement. Sometimes it's obvious: (e.g., Of course you want to give this a name), and I struggle to write the explanation of the obvious, but do it anyway. Sometimes what I think is obvious isn't, at least to someone who is encountering this stuff for the first time. Other times, it isn't so obvious why you need such a thing, or why you chose that way to do it. In these cases, I can really see where this adds value, and not just for other readers. Already I have 20 or so pages of text, and I'm going back through it about every other day. Those little notes are gold when I get to something I wrote a few weeks back and am trying to recall why I did that. Here's an example:
1.
The targetNamespace attribute in the <definitions>
element shall define a unique namespace for the
workflow specification following the rules for creating a formatCode for an
IHE Content profile.
A target namespace is necessary because it can be used to create unique identifiers for elements contained within the workflow specification and relate them to what occurs in an instance of an XDW workflow document. Use of formatCode rules is somewhat arbitrary, but they already exist, and they serve a similar purpose (avoiding name collisions) across IHE profiles, and provide a URN which allows for dereferencing.
A target namespace is necessary because it can be used to create unique identifiers for elements contained within the workflow specification and relate them to what occurs in an instance of an XDW workflow document. Use of formatCode rules is somewhat arbitrary, but they already exist, and they serve a similar purpose (avoiding name collisions) across IHE profiles, and provide a URN which allows for dereferencing.
As we work on standards, I'd love to see more of this sort of explanatory text in both HL7 and IHE specifications. It might make ballot reconciliation or public comment and post publication maintenance a lot easier. It should certainly make implementation easier for the end users of these specifications.
0 comments:
Post a Comment