DataTypes Comments General
Jump to navigation Jump to search
The latest version of this document seems to be quite approachable and flows very well. While I've added quite a few comments, most of them are fairly small and nit-picky in nature. A few non-minor issues remain, including:
- Section 2 still flows choppily. This is an important section as it describes what is going to happen in the rest of the document. I think that it can be improved without a huge rework - just moving some sections and making sure that the introduction aligns with the rest of the sections. I also wonder whether it might be worthwhile moving the syntax for the literal form to the appendix. While it is needed, I'm not certain that anyone is going to read it unless they absolutely have to. It certainly isn't anything that is absolutely required for the understanding of the rest of the document.
- Ockham will make some suggestions.
- "Property" vs. "semantic property" is very confusing, and would really like to see the notion of "semantic property" retired and just deal with plain 'ol properties and what they are defined to (and not to) be. If there is a strong objection to doing this, the authors need to either clarify the distinction between the two and use them consistently or, if there is none always use "semantic property".
- The table formatting leaves a lot to be desired and needs to be given a serious once over.
- There are a lot of examples in section 2 that are labeled as "Definitions"
- The tables in the BL section almost unreadable
- The headings for the concept code tables (OIDs, etc) are cluttered and confusing.
- There seem to be a number of "SHOULD"s, "SHALL"s and their negatives interspersed throughout the document. The vast majority of these simply reiterate the intent of formal constraints. Of the remainder, a portion of them probably should be represented as formal constraints. I would recommend that either (a) the document have one big "SHALL" saying that datatypes SHALL comply with all constraints or, if enumerating them individually is important, (consistently) stash a "SHALL" (or SHALL NOT) after each formal constraint wherever possible. We need to get as many of them as we can out of the rest of the verbiage, as they make the document difficult to read.
- There are also a number of constraints in the form of "HL7 SHALL ...", which I'm not sure that I understand. SHALL / SHOULD and their negatives have to do with defining compliance. "HL7 SHALL..." seems to be a strange way of dictating policy. Have all of these "SHALL's" been brought up for a vote? Have they been implemented? Is HL7 non-compliant if they don't?
- Ockham is also currently listing these uses and some recommendations.