This draft has moved to the openEHR Developer Guide.
The tooling guide is now maintained as a Zensical website. It is the first section of a broader developer guide, with implementation and conformance guidance to follow.
Please post corrections and additions on the openEHR Discourse forum or open a pull request at openEHR/developer.openehr.org.
This is a bit of a ‘starter’ attempt to create a Wikified entrypoint which we can build on. Feedback welcome. I have rough draft content for each of the sections enumerated above, but will post them one by one so I can edit for style and triple-check the details for accuracy.
@SPB as mentioned in the meeting I have started work on this overview, which aims to clarify for new developers/clinicians what tooling is available, what each thing does, and which tools are considered the ‘industry standard’ vs which ones are legacy/deprecated.
Am I on the right track here?
I was thinking to start out first with an inventory of everyting akin of an excel sheet, so it would be easier to filter and distribute the review work.
But if we are comfortable to dive right in the more “human-readable” format, you can count on me to review the lists of applications/software/scripts.
Excel sheets are a disaster area for text. I’m happy for other people to collate a spreadsheet from this data, but I will be continuing with a text-based series of articles.
Agreed! Lets all work on the official text-based documentation.
Can we reuse the open source practise of the list of amazing for x on GitHub?
Explaining all the formats and language seems more of a specs and educational effort seperate from a tooling list to me.
@marcusbaw I know Discourse will be up for what are you proposing with wikified page set - but I was wondering what is your opinion on having a static website, rendered with mkdocs on github pages, based on markdown sources? it is also a “wiki”, easy to maintain, version control, cheap and easy maintenance, visually customisable.
Yes, a static documentation site based on Markdown source could be a better fit for what we want to do than Discourse is.
The reason I didn’t suggest it initially was that I didn’t want to start by suggesting yet another now toolset/platform, when we already have Confluence and Discourse.
However, it could be argued that a static generated site is just leaning more into our existing GitHub presence.
Very happy to go with the static site idea - I have extensive experience with static documentation sites using Material for Mkdocs or Zensical frameworks - but the choice of framework is immaterial as long as the source is in Markdown, it’s easy to switch framework. I know you’ve used Antora a lot, sadly I have no experience with it but I’d give it a go since all openEHR specs are in Antora already.
No, Antora would be too complex for this.
Markdown on github, with static build with Mkdoc is much easier to manage and sufficient for the job, in my opinion.
But it is up for the group to take a direction.
I think everybody here knows markdown and static pages. I personally don’t know Material for Mkdocs or Zensical but I guess with markdown knowledge it’s easy to handle. Let the group decide. Also open for Github pages.
This may be my newcomer brain speaking, so please season generously with salt, but I wonder if there are two slightly different audiences being discussed here: the people maintaining the documentation and the people trying to read and learn from it.
From a maintenance perspective, Markdown in GitHub sounds sensible. My only hesitation is around the reader-facing experience, especially for newer users (like myself) who may not be as familiar with GitHub, Markdown, or the many acronyms floating around.
If the GitHub side is mostly the backend/source of truth, and the output is a well-structured, searchable, visually friendly documentation site, then that seems like a good direction. But I think the success would depend heavily on how beginner-friendly the published site is: clear navigation, introductory pathways, glossary/appendix, and key Discourse learnings surfaced somewhere more permanent.
In other words, my concern is less “GitHub bad” and more “please don’t make the learning curve wear a disguise and call itself documentation.”
Apologies if this has already been covered elsewhere. I’m still deep-diving through Discourse and have accepted that I may emerge in approximately 2037.
Well put @sheeren.khalifa. I think from my understanding of the proposed solutions the rendered git approach would deliver the user friendly interface you’re hoping for. e.g. https://www.mkdocs.org/ is itself built with Mkdocs, with its source editable on Github.
I like @joostholslag’s suggested approach of it being open source itself, where we could have maintainers that could approve any proposed changes through a pull request flow.
That is exactly correct @dmccaf … the sites that are generated my mkdocs are just normal web pages but very easy to put together.
Example here Pharmacogenetics Data Modelling - A Step Towards Personalised Prescribing - openEHR CKM Team UK reviews
And it is not locked into github though gh pages is very convenient
Totally hear this @sheeren.khalifa and the aim will be to make readable, accessible, and less technical documentation than we had before.
I’m fine with any Markdown-on-Git based approach - it gives us simple editable source and it can be presented in a range of ways (even multiple ways from the same source).
MkDocs is going through a little bit of a hiccup right now so I’ve personally transitioned to using Zensical for everything. Here’s an example Zensical-driven site sct - sct
Equally nice is a new framework my son showed me this week called DocMD which is popular in the Rust community.
The difference between all of these is just a few lines of configuration, because for the most part they all consume Markdown as source. If we go with that, we can use anything we want, we can change in the future. It doesn’t matter all that much as long as what we produce is readable, well written, and helpful.
On a side note, I found this PGx modelling page really interesting. I worked on similar modelling in my previous role, where we broke things down in more detail using real PGx reports, so it definitely sparked a lot of thoughts and questions for me.
I can see a few ways this could potentially be made more granular to improve data structuring, although this would depend on the use case ofc, but I won’t go too deep here as I don’t want to add too much noise to the thread. Thanks again for sharing.
Thanks - happy to have a conversation about pgx in a separate topic. The published archetype and example template are at
We are now also working on familial cancer screening and polygenic risk scoring.