Quelltext der Seite 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 http://de.wikipedia.org/wiki/Hilfe:Textgestaltung]

==Grundsätzliches und Gute Praxis der Wiki-Leitfäden==
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 [[Vorlage:Infobox_Dokument|Infobox Dokument]] (auszufüllende Vorlage)
* bei Bedarf eine [[Vorlage:Infobox_Ballot|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 [[Vorlage:HL7transclude|HL7transclude]]
* ein abschließendes <nowiki><references/></nowiki> Tag zum Aufführen aller in Haupt- und Nebendokumenten erwähnten Referenzen.
aus werden die einzelnen Teildokumente transkludiert.

Beispiel
<syntaxhighlight lang="text">
<!--

    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/>
</syntaxhighlight>

===Teildokumente===
Jedes '''Teildokument''' enthält neben dem eigentlichen Text ganz oben an als ersten Text die Vorlage [[Vorlage:DocumentPart|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''
<syntaxhighlight lang="text">
{{DocumentPart}}
= Einleitung =
== Motivation und Ziel ==

Seit der Einführung des... (Text)
</syntaxhighlight>

==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
<syntaxhighlight lang="text">
IG:HL7_CDA_Mutterpass
</syntaxhighlight>

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

Alle zugehörigen Dokumente sind in einem eigenen Wiki-Namespace unterzubringen.
{{AlertBox|
Dazu ist es nicht ausreichend, dass den Dokumenten ein Präfix mit abschließendem ''':''' vorangestellt wird, sondern die ausgezeichneten Wiki-Namespaces müssen gesondert vom Administrator '''vor Anlegen eines Dokuments''' eingetragen werden, damit sie als solche bekannt sind.}}

Beispiel: 
<syntaxhighlight lang="text">
cdaemp:
</syntaxhighlight>
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:
<syntaxhighlight lang="xml">
[[Datei:Bild.jpg|300px]]
</syntaxhighlight>
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:
<syntaxhighlight lang="xml">
{{HL7img|Datei:Bild.jpg|300px|80%}}
</syntaxhighlight>

===Verwendung von Hinweisboxen mit Symbolen===
Grundsätzlich sollte erwogen werden, dass alle Entwürfe wie folgt gekennzeichnet sind.
<syntaxhighlight lang="xml">
{{Underconstruction}}
</syntaxhighlight>
Das ergibt:
{{Underconstruction}}

Es können die folgenden mit Symbolen versehenen Hinweisboxen im laufenden Text gesetzt werden.
{{:Legenda/Boxen}}

Beispiel eines Wiki-Textes:
<syntaxhighlight lang="xml">
{{FAQBox|Diese Information wird in diesem Leitfaden zunächst nicht verwendet.}}
</syntaxhighlight>

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.
<syntaxhighlight lang="xml">
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.
</syntaxhighlight>
<div style="border: 1pt grey solid; padding: 10px;">
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.
</div>
Abbildungen und Tabellen können mit automatisch durchnummerierten Referenzen versehen werden. Hierzu werden die Schlüsselworte "Abbildung" bzw "Tabelle" verwendet.
<syntaxhighlight lang="xml">
{{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
</syntaxhighlight>
Hier wird eine Abbildung referenziert und mit der entsprechenden Bildunterschrift versehen.
<div style="border: 1pt grey solid; padding: 10px;">
{{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
</div>
<syntaxhighlight lang="xml">
{| class="hl7table"
|-
!Section!!LOINC-Code
|-
|... || ...
|}
<ref group="Tabelle">Text der bei der Tabellenreferenz angezeigt wird</ref> ''Tabellenunterschrift''
</syntaxhighlight>

Hier ist eine Tabelle mit entsprechender Tabellenunterschrift aufgeführt.
<div style="border: 1pt grey solid; padding: 10px;">
{| class="hl7table"
|-
!Section!!LOINC-Code
|-
|... || ...
|}
<ref group="Tabelle">Text der bei der Tabellenreferenz angezeigt wird</ref> ''Tabellenunterschrift''
</div>
Am Ende des Dokuments/Abschnitts muss dazu das entsprechende Referenz-Tag eingelöst werden, um die Referenzen alle aufzulisten.

<syntaxhighlight lang="xml">
Referenzen
<references/>

Abbildungen
<references group="Abbildung" />

Tabellen
<references group="Tabelle" />
</syntaxhighlight>
<div style="border: 1pt grey solid; padding: 10px;">
Referenzen
<references/>

Abbildungen
<references group="Abbildung" />

Tabellen
<references group="Tabelle" />
</div>
Wiederholentlich genutzt Referenzen können einen Namen bekommen
<syntaxhighlight lang="xml">
<ref name="xyzref">Die Referenz</ref>
</syntaxhighlight>
...und an anderer Stelle einfach erneut durch Nennung des Namens 
<syntaxhighlight lang="xml">
<ref name="xyzref"/>
</syntaxhighlight>
...referenziert werden.

===Einbinden von farbigen Boxen für verschiedene Zwecke===
====Beispiele im laufenden Text====
...sollten markiert werden mit einer blauen Box.
{{BeginBlueBox|Ich bin ein Beispiel}}
Dies ist der Text in der babyblauen Box
{{EndBlueBox}}
Die Syntax ist
<syntaxhighlight lang="text">
{{BeginBlueBox|Ich bin ein Beispiel}}
Dies ist der Text in der babyblauen Box
{{EndBlueBox}}
</syntaxhighlight>
====Storyboards im laufenden Text====
...sollten markiert werden mit einer violetten Box (BeginPurpleBox, EndPurpleBox):
{{BeginPurpleBox|Ich bin ein Überschrift}}
Dies ist der Text in der Box
{{EndPurpleBox}}

====Weitere Boxen====
...stehen mit BeginGreenBox / EndGreenBox, BeginRedBox / EndRedBox und BeginGrayBox / EndGrayBox zur Verfügung.
{{BeginGreenBox|Ich bin eine Überschrift}}
Dies ist der Text in der Box
{{EndGreenBox}}
{{BeginRedBox|Ich bin eine Überschrift}}
Dies ist der Text in der Box
{{EndRedBox}}
{{BeginGrayBox|Ich bin eine Überschrift}}
Dies ist der Text in der Box
{{EndGrayBox}}

===XML-Darstellung===
Soll XML eingebunden werden, ist dies mit dem Tag ''syntaxhighlight'' wie folgt anzugeben.
<source lang="text">
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>

     oder (als default)

<?xml version="1.0"?>
</syntaxhighlight>
</source>
und erscheint dann zum Beispiel als:
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>

     oder (als default)

<?xml version="1.0"?>
</syntaxhighlight>
Mehr dazu findet sich in der Hilfe zu [[Hilfe:Syntaxhervorhebung]].
<!--
===HL7 Version 2 Nachrichten-Darstellung===
Beispielfragmente, zum Beispiel von HL7 Version 2 Nachrichten, sind einzubinden über die Vorlage [[Vorlage:HL7Example|HL7Example]].
-->

===Angaben zu HL7 V3 Klassen-Attributen===
{{NoteBox|Hinweis: Diese Darstellung ist veraltet. Für CDA-Leitfäden wird in Zukunft der Output des Tools ART-DECOR für die Objekt- und Attributdefinition verwendet. Dabei können Templates einfach in den Wiki-Originaltext transkludiert werden. Voraussetzung dafür ist natürlich, dass die Templates in ART-DECOR eingebracht sind. Mehr dazu unter [[Hilfe:Templates]].

Zum Beispiel ergibt
<syntaxhighlight lang="text">
{{:1.2.276.0.76.10.2010/dynamic}}
</syntaxhighlight>
...folgende Ausgabe
{{:1.2.276.0.76.10.2010/dynamic}}
}}

Klassen-Attribute in HL7 V3 werden grundsätzlich über die Vorlage [[Vorlage:AttDesc|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:
<syntaxhighlight lang="text">
{{AttDesc
| ae = elm
| rim = act, ent, role, part
| name = Encounter
| desc = Begegnung
| dt = 
| card = 1..1
| conf = M
}}
</syntaxhighlight>

Beispiel:
{{AttDesc
| ae = elm
| rim = act
| name = Encounter
| desc = Begegnung
| dt = 
| card = 1..1
| conf = M
}}

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

Wiki-Text für Attribute:
<syntaxhighlight lang="text">
{{AttDesc
| ae = att
| rim = act, ent, role, part
| name = id
| desc = Id des Dokuments
| dt = II
| card = 1..1
| conf = M
}}
</syntaxhighlight>

Beispiel:
{{AttDesc
| ae = att
| rim = act
| name = id
| desc = Id des Dokuments

{{ConstraintBox|Mindestens eine id MUSS als @root 2.1.3.4.5.6 PatientenNummerDeutschland enthalten.}}
| dt = II
| card = 1..1
| conf = M
}}

oder auch als:
{{AttDesc
| ae = att
| rim = act
| name = id
| desc = Id des Dokuments
| dt = II
| card = 1..1
| conf = M
}}

{{ConstraintBox|Mindestens eine id MUSS als @root 2.1.3.4.5.6 PatientenNummerDeutschland enthalten.}}

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

{{NoteBox|Hinweis: Diese Darstellung ist veraltet. Für CDA-Leitfäden wird in Zukunft art-decor für die Objekt- und Attributdefinition verwendet}}

{| class="hl7table"
|bgcolor="ddddff"| || bgcolor="ddddff"| Template-Metadaten
|-
|bgcolor="ddddff"|Template-Typ|| Header oder Section oder Entry 
|-
|bgcolor="ddddff"|Template ID|| <OID für das Template> 
|-
|bgcolor="ddddff"|generischeres Template || <Verweis auf das Template> 
|-
|bgcolor="ddddff"|genutztes Templates || <Verweis auf das Template> 
|-
|bgcolor="ddddff"|nutzende Templates || <Verweis auf das Template> 
|-
|bgcolor="ddddff"|abgeleitete Templates || <Verweis auf das Template> 
|-
|bgcolor="ddddff"|Schwester-Templates ||  <Verweis auf das Template> 
|-
|bgcolor="ddddff"|Generelle Beschreibung||  < direkte Kurzbeschreibung >
|-
|bgcolor="ddddff"|allg. Erläuterung||  < Verweis auf eine allgemeine Erläuterungsseite >
|-
|bgcolor="ddddff"|Verhältnis zu IHE||  dt.Übersetzung oder Ergänzung oder neu
|-
|bgcolor="ddddff"|Ballotierungsstatus||  < Status der Verabschiedung >
|-
|bgcolor="ddddff"|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.

{| class="hl7table"
! Lvl
! RIM 
! Name
! DT 
! Kard 
! Conf
! Beschreibung 

|-
|1
|bgcolor="ff8888"|act
|observation
|
|
|
|

|-
|2
|bgcolor="ff8888"|act
|templateID
|
|
|
|

|-
|2
|bgcolor="ff8888"|act
|code
|
|
|
|

|-
|2
|bgcolor="ff8888"|act
|value
|
|
|
|

|-
| 2
|bgcolor="ffaaaa"| rel
| 
| 
| 
| 
|

|-
| 1
|bgcolor="ccffff"| part
| 
| 
| 
| 
| 

|-
| 2
|bgcolor="ffff88"| role
| 
| 
| 
| 
|

|-
|4
|bgcolor="88ff88"|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).


{{NoteBox|
Bei Wiederverwendung von anderen Templates sollten die Links aufgeführt und die Angaben auf ein Minimum reduziert werden.
}}

==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)