Possible initial ideas (notes from SEC call 15 Nov 2021):
Discuss on Discourse - informal survey on ‘what would you like on the specs site, what’s annoying?’; what order; what docs do you most often use? First time versus experienced use.
Oh boy:
You will not find ‘DvText’ because is actually ‘DV_TEXT’.
If you want to jump directly to class specs, you can use links like https://specifications.openehr.org/classes/DV_TEXT (so https://specifications.openehr.org/classes/{class}). If you prefer UML, you can use the UML-browser Software Engineering Portal.
Is this about the specs-pages (generated from adoc) or about the specs-website (based on bootstrap, which supposed to be responsive)?
Judging be the way you started (“oh boy”), I can assume that problems are quite big from your perspective, so we are happy to hear and tackle them. I do agree there are a lot of things that can/should be improved, but too which extent we can solve them is also a question of resources.
Hi Sebastian,
Sorry about the ‘oh boy’, it’s just as much about my sensitivity to small annoyances as it is about the spec pages:) I just use the specs quite regularly the last few months, so small annoyances start to get remembered. I think you (and the rest) did a pretty good job on the website, thank you for that!
Re dvtext I know it’s not the proper spelling, but since all caps and underscores are hard to type in, it would be nice if dvtext or even ‘text’ would give me some relevant suggestions:)
Nice trick about the url, thanks:)
The iPad ux is mostly about the spec pages, e.g. Architecture Overview
I added a link to class specs mentioned by @sebastian.iancu to my UML browser:
Searching for “dvtext” also works (search is at the top-right of the page).
What I will like to (one day) explore is to build tabbed views for each class, like the ones FHIR’s specs:
It would be nice to include there as tabs textual specifications (adoc), definition of all attributes and functions including the inherited ones, json/xml schema, bmm, json/XML examples and some UML-like view.
Historically we had PDFs;)
The specs are treated as something like standards by many orgs, including ISO, which adopted the AOM2 spec, and need to be able to refer to a document-like thing. They are also docs because the originators (including me) took care to cite prior research and to not write bone-dry SHALL/MUST etc text, but instead something readable and educational, as well, as detailed enough for implementers.
We won’t be able to solve all the UI/UX needs you mention instantly, because the pathway is (most likely) that we need to switch over to BMM being the primary representation of all models and then we have complete power over what we generate downstream from that - UML site; doc-like specs; dev-oriented user specs (using Antora might make sense for that) and so on. Keep the suggestions coming, and we’ll solve what we can over time.
Thanks, knowing the how and the path forward makes it much easier to accept the quirks. I’m really happy by the narrative style of the specs, I was positively surprised at how much it reads like a health informativs handbook. What I’d like is to see is the narrative specs and the related class diagram side by side. Because I often scroll back and forth between them.
And maybe seperate the narrative spec into a handbook with requirements and general insides. And once that can (finally!!) be assumed common knowledge among health informaticians like anyone reading the spec should, the spec can focus on the way openEHR solves those requirements by much more condense narrative text. And people like Gary don’t have to complain about reading hundreds of pages.
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.
another annoyance, when opening a deep link, e.g Common Information Model
on my iPad, it always jumps to the wrong place (too far up/down). I just today learned opening the link again does jump to the right place 
This is actually the design of the ADL Workbench class visualisation and archetype visualisation, and I have a suspicion they borrowed it after seeing it (fine by me). I would like to have a new native version of this again, because it nicely shows inherited attributes as well as attributes from the current class, as well as other tricks, including differential views.
Another really nice view is archetype with non-archetyped RM attributes mixed in.
I’m borrowing your ideas too 
Just added properties from all the ancestors:
p.s.
OBSERVATION even has a documentation in its BMM.
Another request for improvement, if I switch apps back and forth to safari when reading a spec document. It doesn’t remember my reading position correctly, but jumps down quite a lot (without an obvious anchor point)
Change request for Safari maybe - sounds like a browser thing.
Those are all good things to be borrowed again 
but this time on specs-website.
