openEHR Specifications tooling

Target release
Epic
Document status	DRAFT
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

#	Title	User Story	Importance
	Authoring
A1	open standard format	enables multiple tools to edit	Required
A2	text source format	amenable to versioning tools	Required
A3	UML-tool based
A4	Source content directly human readable	editable with generic text editors	Useful
	Publishing
P1	Single source publishing	one set of source artefacts to generate all outputs	Required
P2	Can generate HTML website		Useful

Alternatives

	Tools	Source formats	Ouput formats	Table	Figure	Source code readability	Pros	Cons	Notes
Continue with FrameMaker	Frame, MagicDraw	move to DITA, XMI	PDF, HTML	GUI	GUI	low (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, MagicDraw	DITA, XMI	PDF, HTML, other	GUI	GUI	low (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 + MagicDraw	MagicDraw, HTML tools	XMI, HTML	HTML	HTML source		medium (HTML)
ODF-based solution (MagicDraw)	MagicDraw, Word \| Apache OpenOffice \| ODF tools Achieved using MagicDraw's embedded Velocity statement approach	ODF, XMI	PDF, HTML	GUI	GUI	low (XML)	Easy to edit static content & figures.
ODF-based solution (manual)	MagicDraw, Word \| Apache OpenOffice \| ODF tools	ODF, XMI		GUI	GUI	low (XML)
Asciidoc-based solution	MagicDraw, AsciiDoctor	XMI, AsciiDoc	HTML, PDF, man, EPUB	Character 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 solution	MagicDraw, text editor	markdown text, XMI	HTML, 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 solution	brackets	HTML, CSS	EPUB(Zipped HTML)				e-publishing standard	few 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:

Question	Outcome