Hello everyone,
I’d like to share an update on ongoing work on a new openEHR specification website, built and rendered using Antora.
This effort has been a fairly complex one, the topic was discussed in SEC (Specification Editorial Committee) during the past year, and over the last months I’ve worked the details together with @SevKohler to turn those discussions into a concrete, working implementation.
What this is about?
The goal is to provide a more maintainable, navigable, and future-proof way of publishing the openEHR specifications.
- The site static content is generated with Antora, a documentation site generator designed for large, multi-repository documentation sets.
- Antora is based on AsciiDoc format, which allows specifications to be written in a structured, modular, and versioned way, while still producing high-quality HTML output - this is format however is still the same as we have it now.
- This approach separates content, structure, and presentation, which is particularly important for specifications that evolve over time.
Model foundation changes
A key underlying change is that some of the specification content which was historically derived from UML models has now been migrated to BMM (Base Meta-Model).
- BMM now acts as the authoritative, machine-readable source of model semantics.
- The rendered specification pages consume this BMM-based information.
- This data forms the foundation for the class definition views, which are presented in the site as tabbed sections (e.g. attributes, constraints, inheritance, etc.).
The current development version is publicly available here: https://sebastian-iancu.github.io/antora-openehr. However, this is far for being ready to replace the current website: several links are likely broken, the UI and styling is still the default of Antora, some landing pages are missing, etc. - but you can get an impression about the possibilities & features. For instance: a much evolved search box, better navigation, smaller pages by splitting the old ones, useful tabs, with more class definition information.
Feedback requested
At this stage, I’d like to promote the site to actively request feedback. In particular, I’m very interested in opinions on:
- The overall structure and readability of the specification pages
- The way class definitions are rendered using tabs
- The navigation options - see hyperlinks to switch specification components or versions on the left side of the page footer
- Does this improve clarity? Is important information harder or easier to discover compared to previous representations?
Any feedback -conceptual, editorial, or technical is very welcome and will help guide the next iteration of this work. Thanks in advance for taking a look, and for any thoughts you’re willing to share.
Best regards,
Sebastian