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
_______________________________________________
openEHR-technical mailing list
openEHR-technical@lists.openehr.org
http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org
