Hilfe:StarterGuide

From eHealth Suisse
Jump to: navigation, search

Einleitung

Der folgende Leitfaden soll bei der Nutzung des Wikis unterstützten und die wichtigsten Punkte auflisten, dies es bei dem Arbeiten mit dem WIki zu beachten gilt.

Hinweise

Allgemeine 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

Governance

Für die Arbeiten mit Art-Decor und dem WIki, Verantwortlichkeiten usw. gibt es eine eigene Governance Seite. Diese finden SIe hier: Art-Decor Governance

Arbeiten mit dem Wiki

Versionierung

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. Eine markierte Seite wird genau so festgehalten, wie diese markiert werden, unabhängig davon ob Vorlagen oder auch Unterseiten oder Teil-Seiten in der Zwischenzeit verändert wurden.

Seiten, Unterseiten und Teil-Seiten

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

Grundraster

Als Grundraster kann dafür das Mastertemplate Vorlage:Specification genutzt werden. Um das Mastertemplate einzusatzen, wird die folgende Wikisytax auf der Seite angegeben.

{{subst:Specification}}

Beim Speichern wird der Inhalt der Seite, mit dem Inhalt des Templates ersetzt. Dies gibt die Grundstruktur für das Hauptdokument. Die Platzhalter "@namespace" müssen anschliessend mit dem Namespace der Teildokumente ersetzt werden.

Für die fehlenden Teil-Dokumente gibt es für die meisten eine Vorlage, welche die gleiche Bezeichnung hat und ebenfalls eine Vorstruktur gibt. Der Inhalt kann anaolog dem Mastertemplate auch in das Teildokument kopiert werden. Beispiel Teil-Dokument: wxyz:Abgrenzungen befüllen mit Vorlage Vorlage:Abgrenzungen.

Das Hauptdokument enthält folgende verpflichtend anzugebenden Teile:

  • eine Infobox Dokument (auszufüllende Vorlage)
  • 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 Transclude
  • ein abschließendes <references/> Tag zum Aufführen aller in Haupt- und Nebendokumenten erwähnten Referenzen.

aus werden die einzelnen Teildokumente transkludiert.

Beispiel

<!--

    Implementierungsleitfaden "CDA-CH-VACD"

-->
{{Infobox Dokument{{tt|{{pagelang}}}}
|Title     = Austauschformat eImpfdossier
|Short     = CDA-CH-VACD
|Namespace = vacd
|Type      = Implementierungsleitfaden
|Version   = 2.0
|Date      = 19.04.2018
|Copyright = 2013-2018
|Status    = Pre-Publication Review
|Period    = 2013-2018
|OID       = 2.16.756.5.30.1.1.1.1.3.5.2.1
|Realm     = Schweiz
|LastVersion = 19.04.2018
}}

{{Infobox Ballot Begin{{tt|{{pagelang}}}}}}
{{Ballot | Version = 1.4 | Date = 12.11.2015 | Status = Ausser Kraft | Realm = Schweiz | Otherdocuments = https://www.e-health-suisse.ch/fileadmin/user_upload/Dokumente/2015/D/151112_Austauschformat_Elektronisches_Impfdossier_D.pdf eHS | Comment =  }}
{{Ballot | Version = 2.0 | Date = 19.04.2018 | Status = Pre-Publication Review | Realm = Schweiz | Otherdocuments = https://www.e-health-suisse.ch/fileadmin/user_upload/Dokumente/2018/D/CDA-CH-VACD_de_V20180419.pdf | Comment =  }}
{{Infobox Ballot End}}

<!-- Transcludes für Dokumententeile -->
{{IdentifikationDokument | krzl=CDA-CH-VACD | oid=2.16.756.5.30.1.1.1.1.3.5.2.1 }}
{{TranscludableLink| Page=Ehscda:Impressum/2018 {{tt|{{pagelang}}}} | Pagename=Impressum | Formatting='''}}
{{Autoren{{tt|{{pagelang}}}} | Autoren=Tony Schaller (medshare GmbH); Cornelia Schmid (medshare GmbH) }} 
{{TranscludableLink| Page=Ehscda:ZweckPositionierung{{tt|{{pagelang}}}} | Pagename=Zweck und Positionierung | Formatting='''}}
{{TranscludableLink| Page=Ehscda:Gleichstellung{{tt|{{pagelang}}}}| Pagename=Gleichstellung | Formatting='''}} 
{{TranscludableLink| Page=vacd:ElektronischeVersion{{tt|{{pagelang}}}} | Pagename=Elektronische Version | Formatting='''}}

__TOC__

....

= 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 cdach:Einleitung

{{DocumentPart}}
= Einleitung =
== Ausgangslage und Motivation ==
Die Grundlage für die Austauschformate in der Schweiz bildet die CDA-CH Spezifikation. (...)

Es gibt allgemein gültige Templates welche in allen Leitfäden eingebunden werden können. Sie haben ebenfalls de Namespace ehscda:.

Beispiele dafür sind:

Die folgenden Templates werden jeweils nur als Link eingefügt, welcher aber dann in der Druckausgabe automatisch ins Dokument übernommen wird:

{{TranscludableLink| Page=ehscda:GrundlagenBasistechnologien{{tt|{{pagelang}}}}| Pagename={{TitelGrundlagenTech{{tt|{{pagelang}}}}}} | Formatting===}}<!-- Link -->

Voraussetzungen

Namespaces

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

Beispiel: Das Hauptdokument der Spezifikation Elektronisches Impfdossier - CDA-CH-VACD ist angelegt als

ehscda:CDA-CH-VACD (specification)

Es ist zu beachten, dass die Spezifikation keine Versionsnummern oder dergleichen enthalten.

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

Beispiel:

vacd:

ist der ausgezeichneten Wiki-Namespace für alle Dokumente zum Leitfaden Elektronisches Impfdossier - CDA-CH-VACD . Alle zu diesem Leitfaden gehörenden Dokumente sind mit diesem Namespace-Präfix zu versehen. Das Hauptdokument des Leitfadens selbst ist im Namespace ehscda: 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: Die Spezifikation Elektronisches Impfdossier - CDA-CH-VACD ist in ihre Kapitel aufgeteilt und enthält zum Teil auch Links zu allgemeinen Teilen, welche speziell eingebunden werden.

Typische Kapitel/Abschnitte

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

  • Identifikation Dokument
  • Impressum
  • Autoren
  • Zweck Positionierung
  • Gleichstellung Mann & Frau
  • Elektronische Version
  • Zusammenfassung
  • Einleitung
    • Ausgangslage und Motivation
    • Status und Zweck des Dokuments
    • Angesprochene Leserschaft
    • Ziele und Abgrenzungen
      • Interoperabilität als Voraussetzung
      • Ziele
      • Abgrenzungen
    • Grundlagen und Basistechnologien
    • Verantwortlichkeiten
  • Formelle Grundlagen
    • Bezug zu anderen Standards und Leitfäden
      • IHE Integrationsprofile
      • HL7 V3
      • HL7 Clinical Document Architecture (CDA)
    • Gesetzgebung Elektronisches Patientendossier (EPDG)
    • Übersetzungen
  • Begriffsdefinitionen
  • Anwendungsfälle
    • Einführung
      • Storyboard
      • Fallbeispiele
  • Empfehlungen
    • Transportmechanismus
  • Spezifikation (normativ)
    • Vereinfachte Zusammenfassung der CDA Struktur
      • CDA Header
      • CDA Body
      • Vereinfachte grafische Darstellung des Dokumenteninhalts
    • Allgemeines
      • Schlüsselwörter
      • Optionalität
      • nullFlavor
      • Hierarchie der Spezifikationen
    • Akteure und Transaktionen
    • CDA Struktur
      • CDA Document Level Templates
      • CDA Header Level Templates
      • CDA Section Level Templates
      • CDA Entry Level Templates
    • Codes und Wertebereiche
  • (Tutorial zu IHE Integrationsprofilen)
  • (Abkürzungen und Glossar)
  • Validierung, Technologien und Tools
    • CDA Beispieldokumente
  • Anhang
    • 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.

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 Stichworte lassen sich aus nachfolgender Liste ableiten.

Siehe dazu die folgenden Vorlagen:

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%}}

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[1] bzw. JSON [2] Entwicklung angestoßen.

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

{{HL7img|Cdach pdf editions fr.png|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.

Cdach pdf editions fr.png
Cdach pdf editions fr.png

[Abbildung 1] Dies ist der erklärende Text zur Abbildung als Bildunterschrift

{| class="doc"
|-
!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. Hierfür kann am einfachsten die Vorlage genutzt werden:

{{TitelAnhang{{tt|{{pagelang}}}}}}
{{Anhang{{tt|{{pagelang}}}}}}

Diese enthält gleich alle folgenden Angaben:

Referenzen
<references/>

Abbildungen
<references group="Abbildung" />

Tabellen
<references group="Tabelle" />

Referenzen

  1. Extensible Markup Language (XML) - W3C, https://www.w3.org/XML/
  2. JavaScript Object Notation (JSON): https://tools.ietf.org/html/rfc4627, http://www.json.org

Abbildungen

  1. Die ist der Text, der bei der Bildreferenz angezeigt wird

Tabellen

  1. 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.

Formatierungen

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.


Backup

Die Arbeitsweise ist etwas anders als einem Word Dokument. Es empfiehlt sich die zwischenstände öfters zu speichern.

TODO

  • Transcludes und TranscludableLinks sollten auch genauer beschrieben werden mit einer Anweisung, wann welche Variante genutzt werden soll Status: Offen
  • Das Kapitel «Typische Kapitel/Abschnitte» sollte als Tabelle formatiert werden und in einer 2. Spalte angegeben werden, welcher Teil ab welcher Vorlage genommen werden soll und welcher Teil individuell gestaltet werden soll (incl. Verweis auf ein Best Practice Beispiel) Status: Offen
  • Das Resultat von «Underconstruction» finde ich ungeeignet. Insbesondere der Text «Wenn dieser Beitrag länger als einige Tage nicht editiert wurde, entferne diese Vorlage.» macht bei Projekten, die in der Regel mehrere Monate dauren keinen Sinn. Status: Offen
  • Die HL7 Logos ungeeignet als Hinweis für etwas dass noch abgesprochen werden muss. Status: Offen
  • Prüfungen vor Release in die Governance verschieben Status: Offen