openEHR specifications - the future is Asciidoctor + MagicDraw?

Thomas Beale thomas.beale at oceaninformatics.com
Fri Jul 3 05:37:46 EDT 2015


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 
<https://openehr.atlassian.net/wiki/display/spec/openEHR+Specifications+tooling> 
shows various alternatives under consideration. The other problem *we 
agreed to deal with was to put all openEHR models into a UML *tool 
environment.


      Progress

We'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 
<http://www.openehr.org/releases/trunk/UML/#Diagrams___18_1_83e026d_1423485599937_29309_4372>. 
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 <http://asciidoctor.org/>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 <http://pygments.org/>, 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 formhere
    <https://github.com/openEHR/spec-publish-asciidoc/blob/master/docs/AOM2>;HTML
    view
    <https://rawgit.com/openEHR/spec-publish-asciidoc/master/docs/AOM2/AOM2.html>;
    features to look for: UML tool generated diagrams and specification
    tables;

  *

    ADL specification: source formhere
    <https://github.com/openEHR/spec-publish-asciidoc/blob/master/docs/ADL2>;HTML
    view
    <https://rawgit.com/openEHR/spec-publish-asciidoc/master/docs/ADL2/ADL2.html>;
    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 graphicallyhere 
<https://rawgit.com/openEHR/spec-publish-asciidoc/master/workflow/workflow.html>. 


PDFs are coming - takes some work to get the style sheet into shape.  
The project home page on Github 
<https://github.com/openEHR/spec-publish-asciidoc> 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.

- thomas
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openehr.org/pipermail/openehr-clinical_lists.openehr.org/attachments/20150703/bdee519e/attachment-0002.html>


More information about the openEHR-clinical mailing list