Hilfe:Implementierungsleitfaden: Unterschied zwischen den Versionen
Foemig (Diskussion | Beiträge) K (Code ergänzt) |
(→Voraussetzungen) |
||
(63 dazwischenliegende Versionen von 4 Benutzern werden nicht angezeigt) | |||
Zeile 2: | Zeile 2: | ||
==Einleitung== | ==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. | 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== | ==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. | Leitfäden sind meist lange Dokumente. Es ist deshalb sinnvoll, diese in Teildokumente zu unterteilen, die dann zu einem einzigen Leitfaden zusammengefügt werden. | ||
Zeile 82: | Zeile 88: | ||
Alle zugehörigen Dokumente sind in einem eigenen Wiki-Namespace unterzubringen. | Alle zugehörigen Dokumente sind in einem eigenen Wiki-Namespace unterzubringen. | ||
{{AlertBox| | {{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.}} | + | 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. Die Eintragungen nimmt der Administrator auf in der Datei MediaWiki:ExtraNamespaces vor.}} |
Beispiel: | Beispiel: | ||
Zeile 94: | Zeile 100: | ||
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. | 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== | ==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. | 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=== | ===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. | Es können die folgenden mit Symbolen versehenen Hinweisboxen im laufenden Text gesetzt werden. | ||
{{:Legenda/Boxen}} | {{: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: | Siehe dazu die folgenden Vorlagen: | ||
* [[Vorlage:EMBox]] | * [[Vorlage:EMBox]] | ||
* [[Vorlage:NoteBox]] | * [[Vorlage:NoteBox]] | ||
+ | * [[Vorlage:WorkBox]] | ||
* [[Vorlage:OIBox]] | * [[Vorlage:OIBox]] | ||
* [[Vorlage:FAQBox]] | * [[Vorlage:FAQBox]] | ||
Zeile 111: | Zeile 175: | ||
* [[Vorlage:HL7deBox]] | * [[Vorlage:HL7deBox]] | ||
* [[Vorlage:HL7intBox]] | * [[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> ''Dies ist der erklärende Text als 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> ''Dies ist der erklärende Text als 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=== | ===XML-Darstellung=== | ||
Zeile 138: | Zeile 307: | ||
===Angaben zu HL7 V3 Klassen-Attributen=== | ===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: | Beispiel: | ||
Zeile 156: | Zeile 336: | ||
| ae = elm | | ae = elm | ||
| rim = act | | 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 | | name = id | ||
| desc = Id des Dokuments | | desc = Id des Dokuments | ||
Zeile 162: | Zeile 356: | ||
| conf = M | | 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 | |
− | |||
− | |||
− | { { 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 | {{AttDesc | ||
− | | ae = | + | | ae = att |
| rim = act | | rim = act | ||
| name = id | | name = id | ||
| desc = Id des Dokuments | | desc = Id des Dokuments | ||
− | |||
| dt = II | | dt = II | ||
| card = 1..1 | | card = 1..1 | ||
| conf = M | | 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) |
Aktuelle Version vom 17. April 2019, 10:51 Uhr
Inhaltsverzeichnis
- 1 Wie übertrage bzw. erstelle ich einen Implementierungsleitfaden im HL7 Wiki
- 1.1 Einleitung
- 1.2 Wiki-Hilfe
- 1.3 Grundsätzliches und Gute Praxis der Wiki-Leitfäden
- 1.4 Voraussetzungen
- 1.5 Erstellen / Umsetzen der Spezifikation
- 1.6 Literatur- und Quellenhinweise, Referenzen, Abbildungs- und Tabellenunterschriften
- 1.7 Strukturierung von Leitfäden und deren Inhalten
- 1.8 Ballotierungsstatus
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:
This article or section is in the middle of an expansion or major restructuring and is not yet ready for use. You are welcome to assist in its construction by editing it as well. If this article has not been edited in several days, please remove this template. This page was last edited by Wikiadmin (talk| contribs) 5 years ago. (Purge) Diese Seite oder Abschnitt ist derzeit ein Entwurf und ist noch nicht fertiggestellt. Du bist eingeladen, bei der Fertigstellung mitzuwirken. Wenn dieser Beitrag länger als einige Tage nicht editiert wurde, entferne diese Vorlage. This page was last edited by Wikiadmin (talk| contribs) 5 years ago. (Purge) |
Es können die folgenden mit Symbolen versehenen Hinweisboxen im laufenden Text gesetzt werden.
Dies ist ein Punkt, der besondere Aufmerksamkeit erfordert. |
Dies ist ein einfacher Hinweis. |
Dies ist ein Hinweis auf einen Sachverhalt, der noch bearbeitet werden muss. |
Dies ist ein bekanntes Problem / offener Punkt. |
Dies ist eine häufig gestellte Frage mit Antwort. |
Dies ist ein Punkt, der unbedingt zu beachten ist. |
Dies ist eine Einschränkungsregel. |
Dieser Punkt muss in HL7 Deutschland noch besprochen/abgestimmt werden |
Dieser Punkt muss in HL7 Deutschland oder HL7 International noch besprochen/abgestimmt werden |
Dies ist ein Hinweis auf empfehlenswertes Vorgehen (best practice) |
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.
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.
{| 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 |
---|---|
... | ... |
[Tabelle 1] 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
- ↑ Extensible Markup Language (XML) - W3C, https://www.w3.org/XML/
- ↑ JavaScript Object Notation (JSON): https://tools.ietf.org/html/rfc4627, http://www.json.org
Abbildungen
- ↑ Die ist der Text, der bei der Bildreferenz angezeigt wird
Tabellen
- ↑ Text der bei der Tabellenreferenz angezeigt wird
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.
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):
Dies ist der Text in der Box
Weitere Boxen
...stehen mit BeginGreenBox / EndGreenBox, BeginRedBox / EndRedBox und BeginGrayBox / EndGrayBox zur Verfügung.
Dies ist der Text in der Box
Dies ist der Text in der Box
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
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 {{:1.2.276.0.76.10.2010/dynamic}}
...folgende Ausgabe |
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 |
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
Hinweis: Diese Darstellung ist veraltet. Für CDA-Leitfäden wird in Zukunft art-decor für die Objekt- und Attributdefinition verwendet |
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).
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)