openEHR Specifications tooling

Target release
Epic
Document statusDRAFT
Document owner

Thomas Beale

Designer
Developers
QA

Goals

  • reduce cost of tooling
  • enable multiple users and tools to interact with specifications content 

Assumptions

  • 'Users' assumed to be in the Specifications Editorial Committee

Requirements

#TitleUser StoryImportanceNotes
 Authoring   
A1open standard formatenables multiple tools to editRequired
A2text source formatamenable to versioning toolsRequired 
A3UML-tool based   
A4Source content directly human readableeditable with generic text editorsUseful 
 Publishing   
P1Single source publishingone set of source artefacts to generate all outputsRequired 
P2Can generate HTML website Useful 

Alternatives

 ToolsSource formatsOuput formatsTableFigureSource code readabilityProsConsNotes

Continue with FrameMaker

Frame, MagicDrawmove to DITA, XMIPDF, HTMLGUIGUIlow (XML)

Easy to edit static content & figures.

High quality PDF output.

DITA standard content.

Expensive tooling, Adobe support poor.

No specific integration with UML tool generated content.

 

Move to Madcap Flare

Madcap Flare, MagicDrawDITA, XMIPDF, HTML, otherGUIGUIlow (XML)

Easy to edit static content & figures.

High quality PDFs and other downstream formats.

DITA standard content.

No specific integration with UML tool generated content. 
HTML authoring + MagicDrawMagicDraw, HTML toolsXMI, HTMLHTMLHTML source medium (HTML)   
ODF-based solution (MagicDraw)

MagicDraw, Word | Apache OpenOffice | ODF tools

Achieved using MagicDraw's embedded Velocity statement approach

ODF, XMIPDF, HTMLGUIGUIlow (XML)Easy to edit static content & figures.  
ODF-based solution (manual)MagicDraw, Word | Apache OpenOffice | ODF toolsODF, XMI GUIGUIlow (XML)   
Asciidoc-based solutionMagicDraw, AsciiDoctorXMI, AsciiDocHTML, PDF, man, EPUBCharacter base

Need other tools to make figure.

Size can be attributed.

good (text)well designed for publishing.

requires users' technical skills.

huge documents for specifications.

 
Markdown-based solutionMagicDraw, text editormarkdown text, XMIHTML, PDF

Character base

(need extension)

Need other tools to make figure.

cannot resize original figure.

good (text)

Easy syntax.

Widely adopted to many web applications.

requires users' technical skills.

Not well standardised yet.

poorly support for publishing

need to specify implementation platform, because there are many dialects on syntax.
EPUB based solutionbracketsHTML, CSSEPUB(Zipped HTML)   e-publishing standardfew editor to support ePub3 

Notes from May 21/22 meeting

•Future is a toolchain that generates
–Website(s)
–Documents (PDF capable) – ‘official spec view’
–(versionable) see wiki page
–Change log -
–ePub for tablets etc
–Other? E.g. software dev help files
•From:
–UML models
–Static text
–Other source content?
•Compare with FHIR site
•Different audiences
–Devs – primarily website?
–SDOs – PDFs
–Documentation logical layout – keep current
–Plus think about FHIR-like
•Now:
–Framemaker (TB only, or else buy another licence)
•Medium term:
–Propose to move to ODF docs – Word / Apache OpenOffice - easiest migration
–Use MagicDraw as modelling tool
•Long term:
–Keep MagicDraw (or other UML tool)
–Source format - Asciidoc? DITA?
•Goal – minimise disruption; maintain quality.

Questions

Below is a list of questions to be addressed as a result of this requirements document:

QuestionOutcome

Not Doing