Hilfe:Implementierungsleitfaden
Inhaltsverzeichnis
Wie erstelle ich einen Implementierungsleitfaden
Einleitung
HL7 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.
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
- 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 |Submitted = . |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 Leitfaden ist ein eigenständiges 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
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
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) |
Verwendung XML
Soll XML eingebunden werden, ist dies mit der Vorlage {{HL7XML|...}} wie folgt anzugeben.
{{HL7XML | code = <?xml version="1.0" encoding="utf-8"?> oder (als default) <?xml version="1.0"?> }}
und erscheint dann zum Beispiel als:
<?xml version="1.0" encoding="utf-8"?>
oder (als default)
<?xml version="1.0"?>
Programmkode einer Programmiersprache oder auch sonstige Beispielfragmente, zum Beispiel HL7 Version 2 Nachrichten, sind einzubinden über die Vorlage {{code|...}}.
MSH||||| PID|||||