I wrote most of it as an extension of the huge work that Prof @DavidIngram , Dr Dipak Kalra, Dr Sam Heard, David Lloyd, and others did in GEHR (EU FP3 project), and as a (then) newcomer to health informatics, found we needed to write our own EHR textbook (with requirements and reasons) that also acted as a design spec.
It’s still a bit rough of course, but I’ve come to see that ‘standards’ language belongs in ITS docs - concrete stuff the developers implement directly into code, DBs, APIs etc. The main platform-independent specs (what we call ‘abstract’ specs) give the problem domain analysis and conceptual model of a solution. This still seems to me a reasonable split.
We’d maybe have to think about pop-ups to hold the diagrams or something. I’m not sure actually how to achieve this… maybe your front-end devs have ideas.
I think this applies mainly to the ITS expressions - currently, other than the REST APIs, the ITS expressions are literally just XSDs, JSON schema or other such artefacts. But I think we should build compact specs up around those.