Har til formål at sikre en ensartet udarbejdelse af dokumentation af omtalte komponenter som udvikles til NSP-platformen. Dette er for at sikre en entydig kommunikation omkring de omtalte komponenter og services med henblik på at opnå en hurtig tilslutningsproces for leverandører samt sikre driftmæssige vilkår.



Introduktion

Indeværende dokument indeholder krav til dokumentation, som forudsættes overholdt ifbm. leverancer til NSP projektet.

Dokumentationen, eller dokumentationspakken, for en komponent eller leverance, må leveres sammen med kodebasen, dog er dette ikke et krav. Specielt skal der tages hensyn til følsomme dele af dokumentationen, der ikke må offentliggøres, da det er et generelt krav at kodebasen skal offentliggøre. Det kræves desuden at versioneringen af dokumentationen og koden kan sammenholdes.

En leverance dækker både over kodebasen og dokumentationen, om disse så er adskilte eller ikke. Krav til leverance udover dokumentation er heri ikke beskrevet yderligt.

Krav til dokumentation skal sammenholdes med opsatte krav i dokumentet: Husregler for udvikling til NSP

Formål

I tidligere drifts-regi har der være cirkuleret et dokument, som har drøftet lignende mål, Note om teknisk dokumentation for arkitekturkomponenter fra Silverbullet. Dokumentet har ikke været opdateret siden starten af 2011. Det indeværende dokument skal betragtes som efterfølgeren til omtalte, og samtidigt drage på den erfaring, der er samlet ifm. seneste NSP releases. Dog fokuseres her mere på at lette arbejdet for NSP projektets releaseprocess fremfor at beskrive ønsket indhold. Komponentleverandører er her i stedet ansvarlige for enten at referere til tidligere dokumenter eller selv skønne nødvendigt indhold.

Beskrevne krav skal etablere en uniform struktur for komponentleverancens dokumentation og bidrage til at skabe minimumskrav omkring indhold af denne. Det er ikke meningen at leverede dokumentationen udelukkende skal opfylde disse og ikke mere.

Strukturen skal hjælpe NSP projektet til nemmere at kunne danne sig overblik samt nemt kunne få adgang til nødvendig information ifbm. projektet release faser.

Overordnede krav

De enkelte dele af dokumentationspakken skal så vidt muligt være selvindeholdt – de enkelte dele skal kunne bruges isoleret. Dette skal selvfølgelig opvejes med hvor meget der ønskes gentaget.

Teknisk format

Al dokumentation skal forefindes i et project-space i Confluence på nspop.dk. Alle rettelser til dokumentationen skal foretages via den indbyggede redigering i Confluence, således at den fulde historik for dokumentet er tilgængeligt. I forb. med nye projekter skal der aftales med NSP Operatøren, hvilket project-space på nspop.dk der anvendes. Ifm. leverancer skal der i dokumentet “Leverance beskrivelse" tydelig fremgå, hvilken version af de enkelte dokumenter, som er gældende for leverancen. NSP Operatøren sørger ifm. leverancer for at den nye dokumentation bliver offentliggjort på de sider, der omhandler komponenten.

Leverance

Hvis en leverance indeholder flere delleverenacer, f.eks. i form af flere services, ønskes det ikke at der for hvert af disse findes samme form for dokumentation. Der ønskes i stedet at de forskellige delleverancers dokumentation indgår i den samlede.

Form

Det forudsættes at dokumentationen bliver inddelt i følgende dele. Det skal være synligt hvordan denne opdeling fremkommer:

  1. Leverance beskrivelse
  2. Installationsvejledning
  3. Driftsvejledning
  4. Design og Arkitektur beskrivelse
  5. Guide til anvendere
  6. Guide til udviklere
  7. Test vejledning
  8. Testrapport til sammenligning
  9. Brugerhistorier

I de følgende afsnit beskrives hvad disse inddelinger dækker over.

Leverance beskrivelse

Der forventes heri en beskrivelse af hvad den konkrete leverance indeholder af ændringer. En leverance beskrivelse skal kunne læses som en ændringslog (change log) og give læseren en forståelse for hvad der er ændret i denne leverance. For hver logiske ændring skal der være et sagsnummer fra JIRA samt en tekstuel forklaring af hvorledes ændringen er implementeret.

Hvis en ændring ikke skyldes en bestilling gennem JIRA, skal det tydeligt fremgå hvilken organisation, projektgruppe og person der har bestilt ændringen.

Ifm. beskrivelsen af ændringerne er der ikke tale om en gennemgang af kodeændringerne, men derimod en kort og præcis forklaring af ændringen på et passende abstraktionsniveau. Ud fra beskrivelsen skal en læser der ikke har adgang til kodebasen kunne forstå hvilke koncepter og algoritmer der er ændret, hvordan denne ændring er udført og hvilke konsekvenser dette har på komponenten.

Særligt ved leverance af stamdata importer:

Der sker en transformation af kildematerialet levereret af registerleverandør i importeren før det lander i databasen, eller blot ved selve persistering.

Det er denne transformation, der ønskes beskrives i importernes dokumentation. Dels hvordan det persisteres, og dels en beskrivelse af felterne. Hvis dokumentation fra leverandør eksisterer kan dette delvist tjene formålet, men skal også så vidt muligt generelt medtages.

Dokumentation skal tjene senere anvenderrettet beskrivelse, der kan forklare, hvad SKRS mm. udstiller.

Installationsvejledning

Der forventes heri en beskrivelse af hvordan installationen på NSP platformen skal foretages. Herunder forstås de platforme som indgår i NSP projektet; pt. er det: DoDi, andre backoffice miljøer samt alle NSP-miljøer.

Hvis der er specielle forbehold i visse miljøer, skal dette medtages.

Specifikt forventes følgende at være indeholdt:

  • platformsopsætning
  • platforms- krav/forudsætninger til platform
  • konfigurering af leverance
  • konfigurering/opsætning og evt. migrering af database
  • præliminær smoketests (status side eller lignende)
  • sikkerhedskrav til opsætning
  • generelle opgraderings hensyn hvis nogen

Driftsvejledning

Forhold i forbindelse med drift skal heri beskrives. En driftsleverandør skal i bedste fald udelukkende sætte sig ind i denne del af dokumentationen.

Detalje information:

  • monitoreringssnitflader
  • generel overvågningsflader
  • service snitflader
  • modus operandi – hvordan agere komponenten/servicen
  • håndtering af fejlsituationer
  • beskrivelse af log, hvoraf SLA logpunkter i særdeleshed skal beskrives.

Design og Arkitektur beskrivelse

En overordnet arkitektur- og designbeskrivelse af den funktionalitet som komponenten/servicen leverer. Som vedhæftning til dokumentet skal et Arkitekturdokument vedlægges. Arkitekturdokumentet følger ArchiMate standarden og udarbejdes i open-source-værktøjet Archi.

Arkitekturdokumentet vedligeholdes af leverandøren på basis af en kopi af master Archi arkitekturdokumentationen for NSP, som leverandøren ved start af opgaven henter fra NSP arkitekturdokumentationssiden, og som indeholder en embedded vejledning i udarbejdelse af NSP arkitekturdokumentation.

Som del af en leverance skal der altid enten være lagt fyldestgørende archi arkitekturdokumentation (ny eller opdateret) i forhold til leverancen sammen med den øvrige dokumentationsleverance på confluence samt en side, der beskriver hvilke ændringer, der er foretaget i den nye version af archi arkitekturdokumentationen, eller der skal samme sted på confluence lægges en kort beskrivelse af, hvorfor det i dette tilfælde ikke er relevant med arkitekturdokumentation (det kunne f.eks. være nogle simple mindre kodeændringer, der ikke påvirker løsningens arkitektur).

Guide til anvendere

Denne del er tilegnet klienter til NSP og specifikt den leverede komponent/service. Denne del skal være tilstrækkelig for en klientleverandør, som skal udvikle aftagersystemer.

Heri tilgodeses specielt referencer til andre dokumenter, da en anvender også skal have en bredere forståelse af den anvendte komponent og eventuelle omgivelser. Se <service-navn, template> - Guide til anvendere.

Guide til udviklere

Blandt andet skal denne del indeholde en beskrivelse af hvordan leverancen bygges samt hvordan unittests udføres. Den burde dog være rettet mod udviklere generelt, og ikke blot NSP leverandøren.

Guiden vil også tjene som udgangspunkt for etablering af code coverage resultater, som NSP leverandøren foretager i release processen. Dette ønskes ligeledes tilgodeset.

Testvejledning

NSP projektet udfører en række tests i forbindelse med idriftsættelse, hvori tests fra komponentleverancer i særdeleshed indgår. Derfor er det vigtigt at disse tests er beskrevet i detalje.

Følgende typer af test bruges aktivt i release processen:

  • unittests til etablering af code coverage.
  • integrationstest til verifikation af funktion og deployment.
  • performancetest, som i nogle tilfælde kan anvendes med samme mål som integrationstests.
  • endurancetests, som kan udføres i stagning/produktionslignende miljø.

Integrationstests og performancetest har speciel interesse for NSP projektet, da disse er med til at verificere komponentens funktion sammen med øvrige komponenter i helhed og på den anvendte platform. Beskrivelse af hvad disse tests tester samt hvilken form for testdata, der anvendes, skal også inkluderes her. Desuden skal det i detalje beskrives, hvordan disse tests udføres.

Testrapport til sammenligning

Som grundlag for sammenligning og dokumentation af udført tests ønskes det endvidere at dokumentationspakken indeholder en testrapport udfærdiget af komponentleverandøren.

Testrapporten skal indeholde følgende:

  • code coverage i detaljeret form, sådan at evt. forskelle mellem leverandør og NSP projektets resultater kan sammenlignes.
  • en detaljeret rapport af unittests.
  • performancemålinger
  • endurance test resultater.

Hvis resultater medtages, så skal der i dokumentationspakken være en vejledning til hvordan disse resultater specifikt er frembragt, sådan at de kan verificeres.

Brugerhistorier og testcases

Komponenten/servicen opfylder ét eller flere forretningsmæssige behov. For at synliggøre hvilke behov denne opfylder, skal der udarbejdes én eller flere brugerhistorier.

En brugerhistorie skal beskrives på formen:

SOM EN
<rolle>

ØNSKER JEG
<mål>

SÅ JEG
<rationale>

For hver brugerhistorie skal der være minimum én testcase, men gerne flere afhængig af situationen.

Hvis user story er meget generel, og hvor der kan være flere pre-conditions til samme user-story, vil det kræve at der bliver beskrevet flere testcases.

Eksempel:

  • Som en borger
  • ønsker jeg at lave en uindskrænket søgning i DDS Registry
  • så jeg kan få en liste over mine registrerede dokumenter

Testcase:
Precondition:
Borgeren har et eller flere dokumenter

Action:
Brugeren foretager en uindskrænket søgning i DDS Registry

Postcondition:
Brugeren får en liste retur med ider på alle dennes dokumenter
Der kommer en linje i DDS auditlog

Øvrigt

Dokumentationspakken kan indeholde flere dele end her angivet. Der skal blot kunne skelnes mellem ovenfor anførte og øvrige.