Page History
...
Numbered Headings |
---|
IntroduktionIndevæ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ålI 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 kravDe 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 formatAl 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. LeveranceHvis 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. FormDet forudsættes at dokumentationen bliver inddelt i følgende dele. Det skal være synligt hvordan denne opdeling fremkommer:
I de følgende afsnit beskrives hvad disse inddelinger dækker over. Leverance beskrivelseDer 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. InstallationsvejledningDer 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:
DriftsvejledningForhold 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:
Design og Arkitektur beskrivelseEn 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 anvendereDenne 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 udviklereBlandt 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. TestvejledningNSP 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:
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 sammenligningSom 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:
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 testcasesKomponenten/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 ØNSKER JEG SÅ JEG 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:
Testcase: Action: Postcondition: ØvrigtDokumentationspakken kan indeholde flere dele end her angivet. Der skal blot kunne skelnes mellem ovenfor anførte og øvrige. |