openEHR specifications - the future is Asciidoctor + MagicDraw?

Clinical (archive)
1

Back at the September 2014 roadmap meeting we agreed to move from the current specifications documentation in FrameMaker to a modern tool, preferably text-based. This wiki page shows various alternatives under consideration. The other problem we agreed to deal with was to put all openEHR models into a UML tool environment.

ProgressWe’ve made a lot of progress on both of these. The whole of openEHR is now in MagicDraw, one of the most capable UML tools, with an open API enabling model publishing. You may have seen the generated website here. The models themselves are of course available in the various specifications Github repos. MagicDraw’s native save format is XMI 2.x, which will work with any other UML tool that properly implements XMI.

I’ve been working with Bostjan Lah from Marand on the documentation side, using Asciidoctor as the target. Asciidoctor is asciidoc markdown/up/sideways on steroids + publishing tools for DocBook, HTML, PDF etc. This has entailed converting FrameMaker sources to Asciidoctor sources and building a new toolchain. All of the the model diagrams and formal specification sections in documents are now extracted from the UML models in MagicDraw, by some Java magic that Bostjan has written - so now we have documents that are fully model based, and also can be published into at least 3 formats.

The Asciidoctor toolchain is all open source, as are the related projects (asciidoc-stylesheet-factory, pygments etc), and the developers are very helpful. I’ve also managed to build a pretty good ADL and ODIN code highlighter for Pygments, which hopefully should be accepted into the main project.

MagicDraw, although not open source, is pretty open and very standards-based, and the people there have been very supportive as well.

We are not finished, but it looks as if the Asciidoctor + UML tooling approach will work pretty well, and we will have higher quality documentation than before with much greater flexibility.

What does the result look like? You can get an idea of the results for the re-engineered AOM and ADL specifications:

  • AOM specification: source form here; HTML view; features to look for: UML tool generated diagrams and specification tables;

  • ADL specification: source form here; HTML view; features to look for: machine highlighting using a newly developed ADL mode for Pygments;

The approach to building specification documentation and web resources is shown graphically here.

PDFs are coming - takes some work to get the style sheet into shape. The project home page on Github gives a fuller description of the approach so far.

Benefits

Once a toolchain like this is established, we can get the following benefits:

  • model-based documentation is always up to date, as long as the models are maintained;

  • specifications built like software, under continuous build on server;

  • easier to report and fix errors, and to update documents, due to easy-ish source form;

  • more flexibility to create new output formats.

Future

Right now, the Asciidoctor+MagicDraw approach looks like a solid future solution. Personally I am now seeing the approach as a generic solution for doing single-source technical documentation of any kind for the future - I think we may be onto something quite powerful.

We would be interested in feedback and reactions from the community on this approach.

2

Hello Thomas

This is looking really good and much more usable and lite than shifting through PDFs.

Just a small suggestion / question.

Will it be possible to have (possibly automatically updated from a single model) syntax diagrams for ADL / AQL?

A first step for AQL can be found at:
https://bitbucket.org/aanastasiou/openehr-aql-syntax

Some progress has also been made towards EBNF for ADL at:
https://github.com/aanastasiou/adl_ebnf

Both of these attempts to map the languages were made with the view of creating syntax diagrams which are immensely useful when trying to provide the bigger picture to people with minimal technical background.

The ADL EBNF hit some snags because of various differences in the definitions across different files but in general, it is a straightforward task.

Happy to join forces if something like this is already underway.

All the best
Athanasios Anastasiou

3

Athanasios,

excellent suggestion. I haven't even looked at building in syntax diagrams right now, but your timing is perfect - I was contemplating how to put the ADL grammar into the new style spec in a nice way. Currently grammar is generated as an HTML page (as per links on this wiki page <https://openehr.atlassian.net/wiki/display/ADL/ADL+2+parser+resources&gt;\) which is ok, but the source file is not in a re-usable form (it's a .y file containing Eiffel code - but it would be the same problem with any language like Java or C etc) and the lexer files are also not re-usable or easily publishable.

So we need to solve this in a way that makes the lexer and parser grammar files primary, and then all other files based on them. All of this goes for AQL as well.

Both ADL and AQL grammars can undoubtedly be improved - there is not only one grammar for a language - so making changes for computability doesn't have to break the language definition. I suspect that if we can get some optimal grammars sorted out for Antlr, they will become the 'primary files' for these languages in the ecosystem. Shinji is also after the same thing, and I think has done some work on ADL grammar for Antlr.

So we need to do some work here, and your work looks like a good starting point.

As soon as we have a few more gremlins sorted out in the main toolchain, I'll get myself up to speed on your and Shinji's work here and hopefully we can create a solution which I think then really will make for a powerful models+documentation+programming toolchain.

- thomas