Hilfe:Implementierungsleitfaden

Wie übertrage bzw. erstelle ich einen Implementierungsleitfaden im HL7 Wiki

Einleitung

HL7 Deutschland hat sich zum Ziel gesetzt, alle Implementierungsleitfäden und dazugehörige Dokumente, Terminologien, Templates und sonstiges im Wiki verfügbar zu machen. Um einen Leitfaden hier zu veröffentlichen, sind eine Reihe von Voraussetzungen zu erfüllen und die Leifäden bzw. die zugehörigen Teildokumente müssen nach bestimmten Kriterien erstellt werden, um als Leitfäden oder Teilen davon erkannt zu werden und um die Extraktionsmöglichkeit als PDF-Dokument zu ermöglichen.

Wiki-Hilfe

Das Wiki bietet selbst eine Einführung, wie grundsätzlich mit einem Wiki gearbeitet wird und welche Markups zur Verfügung stehen: http://de.wikipedia.org/wiki/Hilfe:Textgestaltung

Grundsätzliches und Gute Praxis der Wiki-Leitfäden

Alle Seiten des Wiki unterliegen dem Flagged Revisions Verfahren, das es ermöglicht, Seitenversionen zu markieren sowie eine stabile Seitenversion festzulegen (https://www.mediawiki.org/wiki/Extension:FlaggedRevs). Die Seiten werden von so genannten Sichtern freigegeben.

Leitfäden sind meist lange Dokumente. Es ist deshalb sinnvoll, diese in Teildokumente zu unterteilen, die dann zu einem einzigen Leitfaden zusammengefügt werden.

Hauptdokument

Das Hauptdokument enthält folgende verpflichtend anzugebenden Teile:

• eine Infobox Dokument (auszufüllende Vorlage)
• bei Bedarf eine Infobox Ballot (als Begin und End Vorlage) mit den bisherigen Stufen des Dokuments im Abstimmungsprozess
• bei Bedarf eine Liste von Kontributoren dieses Leitfadens, also "vorgelegt von", "mit Beiträgen von", etc.
• die trankludierten separat angelegten Abschnitte, eingefügt mit der Vorlage HL7transclude
• ein abschließendes <references/> Tag zum Aufführen aller in Haupt- und Nebendokumenten erwähnten Referenzen.

aus werden die einzelnen Teildokumente transkludiert.

Beispiel

<!--

    Implementierungsleitfaden "Digitaler Mutterpass auf der Basis von CDA R2"

-->
{{Infobox Dokument
|Title     = Digitaler Mutterpass auf Basis der<br/>HL7 Clinical Document Architecture Release 2<br/>für das deutsche Gesundheitswesen
|Short     = Digitaler Mutterpass auf der Basis von CDA R2
|Namespace = cdaemp
|Type      = Implementierungsleitfaden
|Version   = 1.20
|Date      = 15. Februar 2011
|Copyright = 2010-2011
|Status    = Final Draft
|Period    = Abstimmung
|OID       = n.n.
|Realm     = Deutschland
}}
<!--

-->
{{Infobox Ballot Begin}}
{{Ballot | Version = 1.00 | Date = 18.09.2010 | Status = Entwurf | Realm = Deutschland}}
{{Ballot | Version = 1.10 | Date = 15.02.2011 | Status = Abstimmung | Realm = Deutschland}}
{{Ballot | Version = 1.20 | Date = 15.06.2011 | Status = Kommentarauflösung | Realm = Deutschland}}
{{Infobox Ballot End}}

{{HL7transclude| cdaemp:Einleitung}}
{{HL7transclude| cdaemp:Grundlagen}}
{{HL7transclude| cdaemp:ImplementierungCDA}}
{{HL7transclude| cdaemp:Anhang}}
{{HL7transclude| cdaemp:Abkürzungsverzeichnis}}
{{HL7transclude| cdaemp:Literaturverzeichnis}}

= Referenzen =
<references/>

Teildokumente

Jedes Teildokument enthält neben dem eigentlichen Text ganz oben an als ersten Text die Vorlage DocumentPart um deutlich zu machen, dass dieses Dokument Teil eines Leitfadens ist. Diese Vorlage sorgt automatisch auch dafür, dass das Dokument zur zum Teildokumenten-Namespace gleichnamigen Kategorie hingefügt wird.

Zu beachten ist, dass Teildokumente in einem eigenen Namespace pro Leitfaden (Teildokumenten-Namespace) unterzubringen sind.

Beispiel: Inhalt des Dokuments cdaemp:Einleitung

{{DocumentPart}}
= Einleitung =
== Motivation und Ziel ==

Seit der Einführung des... (Text)

Voraussetzungen

Namespaces

Jeder Implementierungsleitfaden ist ein eigenständiges Wiki-Dokument, dass im Wiki-Namespace IG: anzulegen und zu pflegen ist.

Beispiel: Das Hauptdokument des Leitfadens Digitaler Mutterpass auf der Basis von CDA R2 ist angelegt als

IG:HL7_CDA_Mutterpass

Es ist zu beachten, dass die Leitfäden keine Versionsnummern oder dergleichen enthalten.

Alle zugehörigen Dokumente sind in einem eigenen Wiki-Namespace unterzubringen.

Beispiel:

cdaemp:

ist der ausgezeichneten Wiki-Namespace für alle Dokumente zum Leitfaden Digitaler Mutterpass auf der Basis von CDA R2. Alle zu diesem Leitfaden gehörenden Dokumente sind mit diesem Namespace-Präfix zu versehen. Das Hauptdokument des Leitfadens selbst ist im Namespace IG: angelegt.

Aufteilen der Dokumente

Der gesamte Leitfaden sollte in kleinere Abschnitte unterteilt werden. Sehr sinnvoll ist hier zum Beispiel das teilen in Kapitel oder in logische Abschnitte.

Beispiele: Der Leitfaden Digitaler Mutterpass auf der Basis von CDA R2 ist in seine Kapitel aufgeteilt. Bei Leitfaden Datentypen ist die ebenso der Fall, zusätzlich sind hier die Beschreibungen der einzelnen Datentypen auch noch als kleine Teildokumente vorhanden, damit man ihren Text in anderen Dokumenten transkludieren oder referenzieren kann.

Typische Kapitel/Abschnitte

Ein typischer Leitfaden hat die folgenden Abschnitte bzw. Kapitel. Abschnitte in (Klammern) sind nur zu nennen, wenn es unbedingt notwendig erscheint.

• Dokumenteninformation
  • Impressum
  • Ansprechpartner
  • Disclaimer
  • Autoren
  • Copyright-Hinweis, Nutzungshinweise
  • Danksagung
• Einleitung
  • Rationale
  • Zielsetzung
  • Vorarbeiten
  • Abgrenzung
• (Grundlagen)
• Struktureller Aufbau
  • Verwendeter Standard
  • Übersicht CDA Header und Body
  • (Verwendung von Templates)
• CDA Document Level Templates
• CDA Header Level Templates
• CDA Section Level Templates
• CDA Entry Level Templates
• Terminologien
  • Value Sets
  • Kodesysteme
• Anhang (nicht normativ)
  • Beschreibung der Use Cases und Storyboards
  • Lizenzen
• Referenzen

Erstellen / Umsetzen der Spezifikation

Grundsätzlich können die üblichen Mediawiki-Möglichkeiten genutzt werden. Im Zuge der Vereinheitlichung von Leitfäden, ihrem Layout und ihrer möglichen Wiedergabe als PDF sind einige Vorschläge und Regeln zu beachten.

Hochauflösende Bilder

Grundsätzlich sollten Bilder im SVG Format oder als JPG oder PNG mit mindestens 200dpi eingebunden werden, damit sich in der Druckausgabe damit noch etwas anfangen lässt.

Ohne weitere Maßnahmen werden eingebundene Bilder so im PDF wiedergegeben, wie sie angegeben sind. Das heißt, dass ein Bild, das hochauflösend ist, aber auf nur 300px herunterskaliert ist, auch nur in der schlechteren Auflösung gerastert in in das Druckdokument übernommen wird. Ein übliches Beispiel:

[[Datei:Bild.jpg|300px]]

Um vorhandene hochauflösende Bilder dennoch im PDF mit der maximalen Auflösung wiederzugeben, besteht das Template {{HL7img|bilddatei|xpx|ppc}, wobei eine Bilddatei bilddatei (vorzugsweise SVG bzw. JPG oder PNG mit mindestens 200dpi) im Onlineformat mit xpx Pixeln skaliert wird (wie in einer Image-Anweisung) und für die Druckausgabe ppc % der Seitenbreite einnimmt. Die Skalierung für die Druckausgabe ist dabei wesentlich verlustfreier, da von dem hochauflösenden Original bei der Pdf-Konvertierung skaliert wird. Das vorige Beispiel sieht dann im Quelltext zum Beispiel so aus:

{{HL7img|Datei:Bild.jpg|300px|80%}}

Verwendung von Hinweisboxen mit Symbolen

Grundsätzlich sollte erwogen werden, dass alle Entwürfe wie folgt gekennzeichnet sind.

{{Underconstruction}}

Das ergibt:

Es können die folgenden mit Symbolen versehenen Hinweisboxen im laufenden Text gesetzt werden.

Beispiel eines Wiki-Textes:

{{FAQBox|Diese Information wird in diesem Leitfaden zunächst nicht verwendet.}}

Die anderen Stichwort lassen sich aus nachfolgender Liste ableiten.

Siehe dazu die folgenden Vorlagen:

• Vorlage:EMBox
• Vorlage:NoteBox
• Vorlage:WorkBox
• Vorlage:OIBox
• Vorlage:FAQBox
• Vorlage:AlertBox
• Vorlage:ConstraintBox
• Vorlage:HL7deBox
• Vorlage:HL7intBox
• Vorlage:BestPracticeBox

Literatur- und Quellenhinweise, Referenzen, Abbildungs- und Tabellenunterschriften

Literatur- und andere Quellenhinweise werden über das ref-Element angegeben.

Es wurde eine XML<ref>Extensible Markup Language (XML) - W3C, https://www.w3.org/XML/</ref>
bzw. JSON <ref>JavaScript Object Notation (JSON): https://tools.ietf.org/html/rfc4627, http://www.json.org</ref>
Entwicklung angestoßen.

Es wurde eine XML bzw. JSON Entwicklung angestoßen.

Abbildungen und Tabellen können mit automatisch durchnummerierten Referenzen versehen werden. Hierzu werden die Schlüsselworte "Abbildung" bzw "Tabelle" verwendet.

{{HL7img|Ukfpmp1.jpg|300px|40%}}
<ref group="Abbildung">Die ist der Text, der bei der Bildreferenz angezeigt wird</ref> ''Dies ist der erklärende Text zur Abbildung als Bildunterschrift''

Hier wird eine Abbildung referenziert und mit der entsprechenden Bildunterschrift versehen.

Dies ist der erklärende Text zur Abbildung als Bildunterschrift

{| class="hl7table"
|-
!Section!!LOINC-Code
|-
|... || ...
|}
<ref group="Tabelle">Text der bei der Tabellenreferenz angezeigt wird</ref> ''Dies ist der erklärende Text als Tabellenunterschrift''

Hier ist eine Tabelle mit entsprechender Tabellenunterschrift aufgeführt.

Section	LOINC-Code
...	...

Dies ist der erklärende Text als Tabellenunterschrift

Am Ende des Dokuments/Abschnitts muss dazu das entsprechende Referenz-Tag eingelöst werden, um die Referenzen alle aufzulisten.

Referenzen
<references/>

Abbildungen
<references group="Abbildung" />

Tabellen
<references group="Tabelle" />

Referenzen

Abbildungen

Tabellen

Wiederholentlich genutzt Referenzen können einen Namen bekommen

<ref name="xyzref">Die Referenz</ref>

...und an anderer Stelle einfach erneut durch Nennung des Namens

<ref name="xyzref"/>

...referenziert werden.

Einbinden von farbigen Boxen für verschiedene Zwecke

Beispiele im laufenden Text

...sollten markiert werden mit einer blauen Box.

Ich bin ein Beispiel

Dies ist der Text in der babyblauen Box

Die Syntax ist

{{BeginBlueBox|Ich bin ein Beispiel}}
Dies ist der Text in der babyblauen Box
{{EndBlueBox}}

Storyboards im laufenden Text

...sollten markiert werden mit einer violetten Box (BeginPurpleBox, EndPurpleBox):

Ich bin ein Überschrift

Dies ist der Text in der Box

Weitere Boxen

...stehen mit BeginGreenBox / EndGreenBox, BeginRedBox / EndRedBox und BeginGrayBox / EndGrayBox zur Verfügung.

Ich bin eine Überschrift

Dies ist der Text in der Box

Ich bin eine Überschrift

Dies ist der Text in der Box

Ich bin eine Überschrift

Dies ist der Text in der Box

XML-Darstellung

Soll XML eingebunden werden, ist dies mit dem Tag syntaxhighlight wie folgt anzugeben.

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>

     oder (als default)

<?xml version="1.0"?>
</syntaxhighlight>

und erscheint dann zum Beispiel als:

<?xml version="1.0" encoding="utf-8"?>

     oder (als default)

<?xml version="1.0"?>

Mehr dazu findet sich in der Hilfe zu Hilfe:Syntaxhervorhebung.

Angaben zu HL7 V3 Klassen-Attributen

Klassen-Attribute in HL7 V3 werden grundsätzlich über die Vorlage AttDesc in die Spezifikationen eingebunden. Führend ist hier, ob ein Klassen-Attribut als XML-Element oder XML-Attribut wiedergegeben wird.

Wiki-Text für Elemente:

{{AttDesc
| ae = elm
| rim = act, ent, role, part
| name = Encounter
| desc = Begegnung
| dt = 
| card = 1..1
| conf = M
}}

Beispiel:

	<	Element	DT	Card	Conf	Beschreibung
		Encounter		1..1	M	Begegnung

Im Falle einer Einschränkung auf ein Attribut kann dieses separat oder direkt beim Attribut niedergelegt werden.

Wiki-Text für Attribute:

{{AttDesc
| ae = att
| rim = act, ent, role, part
| name = id
| desc = Id des Dokuments
| dt = II
| card = 1..1
| conf = M
}}

Beispiel:

	@	Attribut	DT	Card	Conf	Beschreibung
		id	II	1..1	M	Id des Dokuments

oder auch als:

	@	Attribut	DT	Card	Conf	Beschreibung
		id	II	1..1	M	Id des Dokuments

Strukturierung von Leitfäden und deren Inhalten

Abschnitte (Sektionen und Entries)

• Die Abschnitte werden alle beginnend auf der zweiten Ebene formatiert.
• Überschrift2: "Section: <Beschreibung>" bzw. "Entry: <Beschreibung>"
• Die Abschnitte enthalten alle zu Beginn einen kleinen Header, der die Identifikation erleichtert:

Template-Metadaten-Tabelle

	Template-Metadaten
Template-Typ	Header oder Section oder Entry
Template ID	<OID für das Template>
generischeres Template	<Verweis auf das Template>
genutztes Templates	<Verweis auf das Template>
nutzende Templates	<Verweis auf das Template>
abgeleitete Templates	<Verweis auf das Template>
Schwester-Templates	<Verweis auf das Template>
Generelle Beschreibung	< direkte Kurzbeschreibung >
allg. Erläuterung	< Verweis auf eine allgemeine Erläuterungsseite >
Verhältnis zu IHE	dt.Übersetzung oder Ergänzung oder neu
Ballotierungsstatus	< Status der Verabschiedung >
Erweiterbarkeit	offen oder geschlossen

• Nach dem Template folgt die Beschreibung mit einer optionalen kleinen Grafik, die den Zusammenhang zwischen den einzelnen Klassen erläutert.
• Danach folgt eine Tabelle, in der die Klassen und ihre Attribute aufgelistet werden:
  • Diese Tabelle wird zukünftig durch ART-DECOR ersetzt. Bis dahin dient sie der Sammlung der notwendigen Informationen.
  • Lvl: Schachtelungstiefe gemäß XML-Darstellung
  • RIM-Element (Attribute werden mit "@" dargestellt.
  • Hier sollte sich auf die Inhalte konzentriert werden.

Lvl	RIM	Name	DT	Kard	Conf	Beschreibung
1	act	observation
2	act	templateID
2	act	code
2	act	value
2	rel
1	part
2	role
4	ent

• Lvl
  • Schachtelungsebene für XML
• RIM
  • farbliche Kodierung des RIM-Elementes
• Name
  • das RIM-Element, d.h. Element oder Attribut-Name (letzterer mit "@" als Präfix)
• DT
  • Datentyp mit Nutzung von nationalen Flavors
• Kard
  • Kardinalität
• Conf
  • M = Mandatory (MUSS-Feld mit gefülltem Inhalt, Null-Flavors nicht erlaubt
  • R = required (MUSS-Feld mit Null-Flavors)
  • opt. = optional (KANN-Feld)
  • NP = not Permitted (verboten)
• Beschreibung
  • textliche Beschreibung des Elements
• An die tabellarische Darstellung der Inhalte schließen sich die Vokabularien an.
• Zu guter Letzt kommt ein Beispiel (in XML).

Ballotierungsstatus

Folgende Status werden im Idealfall bei der Ballotierung durchlaufen. Daraus ist ersichtlich wie weit die Arbeiten zu den Templates, Implementierungsleitfäden oder Spezifikationen im Allgemeinen abgeschlossen sind. Der jeweilige Status lässt sich aus der Metadaten-Tabelle (z.B. Template-Metadaten-Tabelle) entnehmen.

• Entwurf (draft)
• in Abstimmung (review)
• Verabschiedet (active)
• Veraltet (retired)

Ballotierungsstatus für Dokumente/Implementierungsleitfäden

(s.o)

Ballotierungsstatus für Templates

(s.o)