Convert your FHIR JSON -> XML and back here. The CDA Book is sometimes listed for Kindle here and it is also SHIPPING from Amazon! See here for Errata.

Friday, December 4, 2009

On Language and Standards



‘When I use a word,’ Humpty Dumpty said, in a rather scornful tone, ‘it means just what I choose it to mean, neither more nor less.’
‘The question is,’ said Alice, ‘whether you can make words mean so many different things.’
‘The question is,’ said Humpty Dumpty, ‘which is to be master – that’s all.’
As someone who participates in the activities of multiple standards bodies and reads standards published by even more, I am often having to jump between different viewpoints of the world.  If you've studied the dynamics of organizations, you understand that they go through several phases (all of which are necessary), including storming, forming, norming, performing and reforming.  The norming stage includes agreeing on a common language to describe things.  The last few days have highlighted the importance of language: 
  • I need to be able to express something in the language of people in a particular role that I'm not familiar with so that they can understand what I'm saying.
  • I explain that training that I provide is customized to the audience, so that if the class is filled with one set of students, it focuses on their higher level concerns about clinical content, and with another set, on theirs, which is focused on the pointy brackets of the XML.
  • I'm engaged in a discussion with a participant about the differences between the language they are using and the norms of the group they are communicating with.
  • I'm looking to simplify the language used in a specification so that what is being said can be written in a sentence that can be understood by three different audiences with very different languages.
  • I'm battling over the use of terms that are being defined by a group that are at variance with common definitions of those terms used elsewhere.
One of the most time consuming aspects of standards development is in indentifying definitions of things (note that I said identifying and not creating). Definitions are important. They provide the "white lines" that many are looking for to understand the boundaries of a thing. Many times it is the least productive, because nobody can agree on a single definition. This inspires what I consider to be unnecessary invention of new terms to which people can agree on a definition for because they are describing something new rather than trying to fit it into what is already known. This results in needless explanation of new terms that are really reuses of old things in new contexts, and a lot of translation and cross walking between concepts.

Because my mind is on the topic, I spent a few minutes writing up some of what I consider to be best practices around language used in standards:

As a participant in an SDO or Profiling Organization:
  1. Keep it simple.  The more complex a definition is, the less likely that the term it defines will be readily understood. 
  2. If you need to give something a name, make it a name that can be interpreted from the words in it without a definition (but still define it), or better yet, use a term that has a definition that suits, and cite your reference. 
  3. Use readily available and well recognized sources for definitions of terms.  I happen to prefer dictionaries like Websters or the American Heritage Dictionary as my source of definitions, or when necessary, dictionaries of computer terms, and lastly definitions created by well recognized organizations with broad participation rather than those that are specific to a single field of practice.
  4. Keep sentences simple and understandable by as broad a group as possible.  Remember that your audience likely contains the top-most C-levels of an organization right down to the recent college graduate responsible for implementing some portion of a system. 
  5. Avoid use specially coined terms that will be recognized and properly understood only by someone who has been participating in your organization for years (the phrases "class clone" and "transaction package" come to mind).  This is especially true in material that someone outside your organization needs to understand.
  6. Do create a glossary of technical terms that provides definitions and cites references to help new members.
  7. Avoid creation of new acronyms.  These are the least comprehensible to someone outside your organization.
  8. When you find cases where a different understanding terms results in different meaning, make sure you clarify it in what is published.  If it took your group an hour to resolve issues that result from different understandings of the term, don't assume that your readers will automatically have the same understanding of those terms when you publish.
  9. Provide real-world examples.  They are often the simplest way to express what is happening in ways that everyone can relate to.
As a new participant in and SDO activity:
  1. Ask for the glossary of terms.
  2. Ask for definitive references and resources.
  3. Try to understand the terms being used by the group using the group norms instead of your own, but also...
  4. Ask for clarification when you don't  understand a term or acronym.
  5. If you find yourself disagreeing with a statement, see if the source of the disagreement is in your understanding of the terms used in the statement.  So many times I've seen the reconcilliation of a disagreement resolved by ensuring that everyone has the same understanding of the terms being used.
  6. Ask for a real world example.
I'd love to see the various SDOs and profiling organizations to individually agree on a set of definitive published reference works that they will use and cite for definitions.  If we could get them all to agree collectively on these references, I'd be even happier.