Skriva IG dokumentation

För att artefakterna i en IG ska kunna förstås och använda som avsett krävs att deras sammanhang och användningsområde beskrivs. En IG i VGR har sådan information på sidorna Home och Designval samt ovan och under den del av de andra sidorna som skapas av IG Publisher.

På denna sida beskrivs vad som ska framgå på dessa sidor och hur de skapas.

Home

Home ska innehålla följande rubriker:

### Introduktion
bla bla bla

#### Målgrupp
bla bla bla

#### Användningsfall
##### Användningsfall 1
##### Eventuellt Användningsfall 2
##### och så vidare

#### Ingående profiler
bla bla bla

Sekvensdiagram

För varje användningsfall ska det finnas ett sekvensdiagram som visar information som är relevant för sekvensen, t ex för villkorade delflöden. Diagrammet ska visa de ingående informationssystemen, vilka informationsmängder som efterfrågas och delas samt vilka resurser som används.

Klassdiagram

Under Ingående profiler ska det finnas ett klassdiagram som visar de ingående profilerna och de element som ska användas. De element som är med i klassdiagrammet sätts som MS i profilerna.

Se nedan för hur diagrammen skapas.

Designval

Vägval av betydelse för innehållet i en Implementationsguide skall redovisas på sidan Designval, så att den som läser IGn förstår bakgrunden till dessa.

Rubriknumrering

Innehållet i en websida ska underordnas sidans eget indexnummer som blir huvudrubrikens nummer, dvs nr 1 för index.html medför en huvudrubrik 1 Home. För att underrubriker ska inordnas korrekt SKALL dessa numreras med början på markdown-nivå 3,dvs ### som högsta nivå.

Exempel:

### Introduktion
bla bla bla

#### Fördjupning
bla bla bla

resulterar i:
1 Home
1.1 Introduktion
bla bla bla
1.1.1 Fördjupning
bla bla bla

Sekvens och klassdiagram

Diagrammen görs i plantUML, utgå från mallarna som finns på git.
Ytterligare information finns på plantuml.com.
Använd en plantuml extension, till exempel Rich PlantUML support for Visual Studio Code.

Namnge filerna IGnamnSequenceDiagram.plantuml resp IGnamnClassDiagram.plantuml.
Exempel: VGRreimbursementClassDiagram.plantuml

Spara plantUML-filerna i mappen “input/images-source”.

När IG publisher körs görs en .svg för varje plantUMLfil i mappen. Dessa inkluderas på websidan med koden:

{% include < NamnPumlfilUtanFiltyp >.svg %}

Exempel:

{% include VGRreimbursementSequenceDiagram.svg %}
{% include VGRPUServiceSequenceDiagram.svg %}

Länkar

Länka gärna till externa källor som använts eller som läsaren kan ha nytta av. Skriv länken enligt mönster “läs gärna mer på”[denna intressanta sida](/anvisningar/profilering/www.intressantasidan.se){:target=”_blank” rel=”noopener”}. Kodsträngen efter länken gör att sidan öppnas i ett nytt fönster.

Exempel:

...with the same profiling as [SE base Organization R4 1.0.0](https://hl7.se/fhir/ig/base/1.1.0/StructureDefinition-SEBaseOrganization.html){:target="_blank" rel="noopener"}

Intro och Notes på artefakternas sidor

Det finns möjlighet att infoga beskrivningar (text) i den websida som genereras för varje artefakt. Det rekommenderas att skriva information under intro för “Scope and usage” (Tillämpningsområde och användning) och “Must Support, Mandatory Elements, and Cardinality” (Must support, obligatoriska element och kardinalitet) som förklarar eventuella anpassningar som gjorts i profilen. Under Notes kan ytterligare information tillföras vid behov.

Projektets *-intro.md och *-notes.md filer ska sparas i mappen input/intro-notes.

Filerna namnges enligt mallarna:
<resourceType>-<artefaktens namn>-intro.md
<resourceType>-<artefaktens namn>-notes.md
Exempel: StructureDefinition-VGRBasePatient-intro.md

Se nedan under ‘Hur det fungerar’ för beskrivning av hur SUHSI använder dessa filer.

Mallar

Mallar nedan bör användas för innehåll i -intro.md och -notes.md.

Intro

Mallen ska användas avseende rubriker och dess nivå.

### Scope and Usage
bla bla bla

### Must Support, Mandatory Elements, and Cardinality
bla bli bla

Notes

Denna del hamnar under en egen rubrik “Notes” där man välja att skriva ett stycke text och/eller skapa stycken under separata rubriker. Sådana separata rubriker ska då utgå från nivå enligt mallen nedan. Rubrikerna i mallen är förslag att använda vid behov.

Valfri text som hamnar direkt under befintlig rubrik "notes".

#### Obligatoriska sökparametrar
bla bla

#### Frivilliga sökparametrar
bla bla

Hur det fungerar

För varje fsh-artefakt skapar SUSHI build en JSON-fil namngiven på mönstret
{resourceType}-{Id}.json
exempel:
StructureDefinition-VGRBasePatient.json

När IG publisher körs kommer html-filer att genereras för varje sådan json-fil. Om publisher hittar en html-fil med samma filnamn + suffix “-intro” eller “-notes” kommer innehållet i dessa att infogas i början respektive slutet av resulterande html-fil. Dessa intro/notes html-filer genereras som övriga narrativ från innehåll som redigeras i markdown.

För referens se US-Core IG Careplan