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 | Notes |
|---|---|---|---|---|
| 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 | 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 |
|---|---|