Hilfe:Implementierungsleitfaden: Unterschied zwischen den Versionen
Foemig (Diskussion | Beiträge) (→Templatestatus) |
(→Templatestatus) |
||
Zeile 402: | Zeile 402: | ||
==Templatestatus== | ==Templatestatus== | ||
− | * | + | * Entwurf (draft) |
− | * in | + | * in Abstimmung (review) |
− | * | + | * Verabschiedet (active) |
− | * | + | * Veraltet (retired) |
Version vom 11. Juli 2013, 12:15 Uhr
Inhaltsverzeichnis
- 1 Wie übertrage bzw. erstelle ich einen Implementierungsleitfaden im HL7 Wiki
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
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.
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.
Verwendung von Hinweisboxen mit Symbolen
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
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 und BeginRedBox/EndRedBox 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
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
Template-Metadaten | |
Template-Typ | Header oder Section oder Entry |
Template ID | <OID für das Template> |
genutztes Template | <Verweis auf das Template> |
abgeleitete Templates | <Verweis auf das Template> |
Generelle Beschreibung | < direkte Kurzbeschreibung > |
allg. Erläuterung | < Verweis auf eine allgemeine Erläuterungsseite > |
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. |
Dokumentstatus
Die Statusinformation zu Beginn eines Leitfadens soll eines von folgenden Werten enthalten:
- Entwurf (in Ausarbeitung)
- in Abstimmung
- Überarbeitung (Auflösung von Kommentaren)
- Finalversion (fertig gestellte und verabschiedete Version)
Templatestatus
- Entwurf (draft)
- in Abstimmung (review)
- Verabschiedet (active)
- Veraltet (retired)