Bijlage II: Documentatie

Transcriptie

1 RWS BEDRIJFSINFORMATIE Bijlage II: Documentatie Datum 13 februari 2017 Status Definitief

2

3 RWS BEDRIJFSINFORMATIE CONCEPT Bijlage II: Documentatie 13 februari 2017 Colofon Uitgegeven door Rijkswaterstaat Water Verkeer en Leefomgeving Informatie M. van den Berg Telefoon Fax Uitgevoerd door M. van den Berg Opmaak Datum 13 februari 2017 Status Definitief Versienummer 1.0

4

5 RWS BEDRIJFSINFORMATIE CONCEPT Bijlage II: Documentatie 13 februari 2017 Inhoud Inleiding 7 1 Algemeen Producten Samenhang met inhoudelijke onderwerpen Planning Achtergronddocumenten 10 2 Beschrijving per document Structuur van de documentatie Hoofddocumentatie software Functionele documentatie Technische documentatie Systeemdocumentatie Hoofddocumentatie data en kwaliteit Datarapport Schattingsrapport Analyserapport Testplan Testrapporten Hoofddocumentatie gebruikersinformatie Gebruikers handleiding Toepassingsbereik Kaders Leveringsvoorwaarden Aanvraagformulier Geheimhoudingsverklaring Overkoepelende projectdocumentatie Projectverslag 15

6

7 Inleiding De documentatie van BasGoed bestaat momenteel uit een verzameling van verschillende rapporten en memo s. Iedere module is op een ander detailniveau gedocumenteerd. Dit maakt het geheel onoverzichtelijk waardoor de benodigde informatie niet effectief teruggevonden kan worden. Doel van dit project is om een complete set standaarddocumentatie van BasGoed op te stellen, gebruik makend van de bestaande memo s en rapporten. Er wordt een nieuwe structuur gekozen, waarin de bestaande documentatie wordt opgenomen, aangevuld met de documenten die voor de verschillende inhoudelijke onderwerpen gemaakt zijn. Pagina 7 van 15

8 1 Algemeen 1.1 Producten De gewenste hoofddocumentatie kan grofweg worden opgedeeld in documentatie van de software, data, en documentatie t.b.v. gebruik. Daarnaast wordt een viertal, voor BasGoed2018 overkoepelende, documenten gevraagd. Deze kunnen vrijwel compleet worden samengesteld o.b.v. de rapporten opgeleverd vanuit de betreffende inhoudelijke onderwerpen. De gewenste software documentatie ten behoeve van het beheer van BasGoed bestaat uit: - Functionele documentatie: functionele specificaties, beschrijving wat het model (en elk onderdeel binnen het model) doet en proces diagrammen. - Technische documentatie: beschrijving van de technische/wiskundige werking van het model (en elk onderdeel binnen het model), beschrijving van hoe de functionaliteit is geïmplementeerd en data flow diagrammen. - Systeemdocumentatie: architectuurontwerp en uitwerking hiervan met beschrijving hoe de verschillende onderdelen geïmplementeerd zijn, beschrijving van de interfaces en van de benodigde hardware en software omgeving(en). Bovendien worden hierin de installatie-instructies ten behoeve van in beheer name opgenomen. Voor de software documentatie wordt de JSTD016 standaard als uitgangspunt genomen, waarin de hoofdstuk indeling in overleg met RWS naar inzicht wordt aangepast. De gewenste data- en kwaliteitsdocumentatie van BasGoed bestaat uit: - Datarapport: exacte invulling/waarden gebruikt bij de beschreven versie van BasGoed - Schattingsrapport: hoe de schatting is uitgevoerd, wat de resultaten zijn - Analyserapport: beschrijving van het functioneren van het model, welke systeem en data analyses zijn uitgevoerd en welke inzichten dit heeft opgeleverd - Testplan: per type test (unit testen, integratietesten, gebruikersacceptatietest) beschrijving van de testfilosofie, te gebruiken methodes en tools, testspecificaties en acceptatiecriteria - Testrapporten: per type test (unit testen, integratietesten, gebruikersacceptatietest) beschrijving van de uit te voeren testscenario s, resultaten van de testen, het aantal uitgevoerde en geslaagde testen, omschrijving van de oorzaak van het falen en een restpuntenlijst (door RWS in te vullen) Voor de testdocumentatie wordt de JSTD016 standaard als uitgangspunt genomen, waarin de hoofdstuk indeling in overleg met RWS naar inzicht wordt aangepast. De documenten rondom het gebruik van BasGoed: - Gebruikershandleiding: hoe bedien je BasGoed - Toepassingsbereik: wat kan BasGoed wel en niet; moet antwoord geven op de vraag van de gebruiker of het model gebruikt kan worden in zijn/haar studie. - Concept kaders: welk proces moet doorlopen worden als je BasGoed wilt toepassen - Leveringsvoorwaarden: onder welke voorwaarden mag je BasGoed gebruiken - Aanvraagformulier: formulier voor het aanvragen van het BasGoed model door de gebruiker Pagina 8 van 15

9 - Geheimhoudingsverklaring: door de gebruiker te ondertekenen verklaring bij het gebruik van gedetailleerde BasGoed bestanden Voor een voorbeeld van deze documenten zie de bijgeleverde achtergronddocumentatie. Tijdens het project zullen ook meerdere specificaties en memo s geschreven worden. Alle relevante tussenproducten moeten uiteindelijk opgenomen worden in de gedefinieerde eindproducten, waardoor het lezen van losse memo s niet meer nodig is. Het project wordt afgesloten met een projectverslag, waarin ook werkzaamheden/onderzoeken/keuzemogelijkheden/bewandelde paden beschreven worden die niet direct tot aanpassingen in de officiële documentatie hebben geleid, of die als achtergrondinformatie dienen. Alle documentatie dient in de Nederlandse taal geleverd te worden. Opdrachtnemer dient RWS ervan te verzekeren dat alle opgestelde documenten gecontroleerd zijn op correctheid, volledigheid en leesbaarheid vóór oplevering. De relatie tot de productseries zoals omschreven in het hoofddocument van de vraagspecificatie BasGoed2018 is als volgt. Productserie 1 t/m 3 bevat conceptversies van functionele, technische en systeemdocumentatie, specificaties, datarapport, het analyserapport, testplan, testrapport en het projectverslag. In productserie 4 wordt dit uitgebreid met het schattingsrapport en de schattingshandleiding. Productserie 5 bevat het analyserapport, toepassingsbereik en projectverslag. In productserie 6 worden kader, leveringsvoorwaarden, aanvraagformulier en geheimhoudingsverklaring toegevoegd, en worden alle ander documenten definitief gemaakt. 1.2 Samenhang met inhoudelijke onderwerpen Alle inhoudelijke onderwerpen binnen BasGoed 2018 leveren een bijdrage aan de documentatie. Daarom is het belangrijk dat de structuur van de documentatie zo vroeg mogelijk in het project wordt vastgesteld. Vanuit de inhoudelijke onderwerpen kan dan gelijk in de juiste structuur gewerkt worden. Bij de inhoudelijke onderwerpen wordt in sommige gevallen gevraagd om memo s met overzichten, analyses en/of adviezen. Deze memo s moeten in de uiteindelijke documentatie terecht komen, waardoor het niet nodig is om naar losse memo s te verwijzen. 1.3 Planning - Na het eerste increment moet een voorstel voor de structuur van de documentatie beschikbaar zijn. Na goedkeuring door WVL wordt in de rest van het project de documentatie verder in deze structuur uitgewerkt. - Tijdens de voorbereidings-, implementatie-, herschattings- en analysefase worden de documenten steeds verder aangevuld. Hierbij moeten steeds conceptversies aan opdrachtgever worden voorgelegd, zodat eventuele reacties gelijk meegenomen kunnen worden in een volgende versie. - In de opleveringsfase worden de documenten afgerond, en wordt de laatste concept versie opgeleverd. Deze wordt door WVL doorgelezen, waarna opdrachtnemer de opmerkingen verwerkt. Hierna wordt de definitieve versie opgeleverd. - Pagina 9 van 15

10 1.4 Achtergronddocumenten Alle achtergronddocumenten genoemd in de vraagspecificatie vormen input voor de nieuw op te stellen documenten. LET OP: voordat gestart wordt met het aanpassen van Toepassingsbereik, Kaders, leveringsvoorwaarden, aanvraagformulier en geheimhoudingsverklaring moet de op dat moment meest recente versie opgevraagd worden bij RWS. De bij de uitvraag meegestuurde versies zijn voorbeelden, maar kunnen nog wijzigen gedurende de looptijd van het project. Pagina 10 van 15

11 2 Beschrijving per document In dit hoofdstuk worden alle documenten op hoofdlijnen beschreven. 2.1 Structuur van de documentatie Als eerste stap in het opstellen van de documentatie wordt opdrachtnemer gevraagd een voorstel te doen voor de structuur/opzet van de verschillende documenten. Deze structuur dient, na goedkeuring door WVL, als basis voor de rest van het project. In het voorstel moet op zijn minst een overzicht worden opgenomen van wat in welk document beschreven zal worden en hoe omgegaan zal worden met hoofdstukindeling en module-/bestandsnummering. Vervolgens moet inzichtelijk worden gemaakt hoe de bestaande documentatie zal worden hergebruikt en welke aanpassingen hierin zijn voorzien, bijv. welke selectie van onderdelen in welke documentatie terecht zal komen. 2.2 Hoofddocumentatie software Functionele documentatie Het doel van de functionele documentatie is het beschrijven wat het model (en elk onderdeel binnen het model) doet, voornamelijk ten behoeve van het verklaren van modeluitkomsten. Het begint met een korte samenvatting (ca. 1 pagina) voor mensen die een absolute basiskennis van BasGoed hebben. Daarna volgt een overzicht van het geheel: welke modules zijn er, wat rekenen deze op hoofdlijnen uit, en welke relatie hebben de modules tot elkaar. Vervolgens moeten deze modules stuk voor stuk beschreven worden. Hierbij gaat het om het doel van de module en de theoretische beschrijving van de gebruikte modellen. Denk hierbij bijvoorbeeld aan formules en neststructuren die gebruikt zijn, afsplitsingen van specifieke stromen, mogelijke beleidsinvoer. Belangrijk is dat het mogelijk is om bepaalde stromen te kunnen volgen, zodat uitkomsten verklaard kunnen worden. Ook gemaakte aannames moeten worden beschreven, en de hieruit volgende effecten op de resultaten. Tenslotte moeten een aantal specifieke onderwerpen apart worden beschreven. In ieder geval zijn dit de zone-indeling en kostenparameters. Welke onderdelen hiernaast een aparte beschrijving behoeven, zien we graag terug in de eerst op te stellen beschrijving van de structuur van de documentatie Technische documentatie De technische documentatie geeft een beschrijving van de technische werking van het model. Het bevat een beschrijving van de datastromen (stroomdiagrammen), bestandsbeschrijvingen, en het geeft per (sub-)module aan welke bewerkingen er worden uitgevoerd. Een belangrijk onderdeel van de technische documentatie is het huidige datamodel. Hieraan moeten de uitgevoerde bewerkingen per module worden toegevoegd. Een aantal onderdelen zullen verplaatst moeten worden naar de functionele documentatie. Tijdens de voorbereidingsfase worden voor de nieuwe of aangepaste onderdelen specificaties opgesteld. Deze specificaties kunnen gebruikt worden om, na het programmeren, de technische documentatie op te stellen. Pagina 11 van 15

12 2.2.3 Systeemdocumentatie De systeemdocumentatie beschrijft hoe de verschillende onderdelen geïmplementeerd zijn in de software. Het beschrijft het architectuurontwerp van BasGoed: een Ruby basis waaraan alle verschillende modules, elk in hun eigen programmeertaal, gekoppeld zijn. Dit ontwerp moet duidelijkheid bieden bij het beheren van de code en bij het ontwikkelen van nieuwe modules, zodat een eenduidige en eenvoudig te onderhouden structuur ontstaat. De systeemdocumentatie bevat tevens een beschrijving van hoe de code is opgebouwd en welke unit tests en integratietests geïmplementeerd zijn, vergelijkbaar met de systeemdocumentatie zoals die opgesteld is voor de rittenmodule en corridorkeuzemodule (deze is te vinden binnen de technische documentatie Rittenmodule en Corridorkeuzemodule). In de systeemdocumentatie moeten ook de instructies voor de compilatie van alle onderdelen van BasGoed zijn opgenomen, net als een beschrijving van de installatieprocedure. De gebruikte unit- en integratietests moeten worden beschreven, net als de te volgen werkwijze om deze (geautomatiseerd) uit te voeren. 2.3 Hoofddocumentatie data en kwaliteit Datarapport Functionele, technische en systeemdocumentatie beschrijven de (inhoudelijke werking van de) software en zijn in principe onafhankelijk van de waarden van de parameters en databestanden. In deze documenten krijgen alle bestanden een naam of code. In het datarapport wordt de naam van deze bestanden benoemd en worden juist de gebruikte waarden opgegeven. Het datarapport is een invulling van de bestanden en parameters zoals die beschreven zijn in de technische documentatie. Zoveel mogelijk relevante tabellen, lijsten en parameters moeten worden opgenomen. Invoerbestanden die in andere projecten of door andere modellen gegenereerd zijn, moeten genoemd worden met een verwijzing naar de bijbehorende documentatie. Denk bijvoorbeeld aan de basisbestanden goederenvervoer, prognoses met LMS, BIVAS, NEMO en het zeevaartbestand. De wijze waarop de bestanden opgesteld zijn hoeft NIET in het datarapport beschreven te worden. De memo s die hierover voor de verschillende databestanden zijn opgesteld, moeten worden opgenomen in het projectverslag Schattingsrapport Het schattingsrapport geeft een overzicht van het schattingsproces en de uitkomsten. Er zijn vier belangrijke onderdelen: - Overzicht van het schattingsproces: een opsomming van alle te schatten parameters, opsomming en korte beschrijving van speciaal voor de schatting op te stellen databestanden en een overzicht van standaard te bepalen elasticiteiten. - Gebruikte data: beschrijving van de verzamelde data en de bewerkingen die erop uitgevoerd zijn. Hierbij gaat het zowel om data die als invoer voor BasGoed gebruikt is ten tijde van het schatten, als om de datasets die daarnaast nodig zijn om de schatting uit te voeren. Pagina 12 van 15

13 - Schattingswerkzaamheden: beschrijving van de gevolgde werkwijze bij het schatten, de verschillende geschatte structuren, resultaten en de uiteindelijk gemaakte keuzes. Beschrijving van de resulterende elasticiteiten en een vergelijking met relevante benchmarks. Voor verschillende inhoudelijke onderwerpen wordt data verzameld. Deze databestanden worden in principe in het datarapport beschreven. Bestanden gebruikt t.b.v. de schattingen moeten echter (tevens) in het schattingsrapport beschreven worden, net als de bewerkingen die speciaal voor de herschatting op deze data zijn uitgevoerd. Uitgebreide analyses van deze data hoeven niet in het schattingsrapport, maar komen in het projectverslag of analyserapport. Het kan echter ook zo zijn dat voor de schatting specifieke datasets verzameld zijn. Beschrijving van de gevolgde werkwijze voor het inzamelen en de analyseresultaten van deze specifieke datasets moeten wel in het schattingsrapport beschreven worden. In het overzicht van het schattingsproces wordt gevraagd een overzicht van standaard te bepalen elasticiteiten te geven. Het doel van het vaststellen van standaard elasticiteiten is het vergelijkbaar maken van verschillende versies van het model. Door steeds dezelfde elasticiteiten uit te rekenen en op dezelfde manier te presenteren, wordt het eenvoudig om verschillende versies van het model te vergelijken. Er zijn veel verschillende elasticiteiten mogelijk (per module, per mode, ). Graag ontvangen we een voorstel waarin elasticiteiten zijn opgenomen die het meest zeggen over de kwaliteit van het model en elasticiteiten die gerelateerd zijn aan veel gestelde beleidsvragen Analyserapport Dit rapport geeft inzicht in het functioneren van het model. Tijdens de analysefase worden verschillende analyses en tests uitgevoerd. Door deze tests wordt inzicht verkregen in de kwaliteit van het model. In het rapport met analyseresultaten moet deze kwaliteit getoond worden. Het analyserapport bevat hoofdstukken met daarin de resultaten van analyses met betrekking tot verschillende inhoudelijke onderwerpen, nieuwe modules en verzamelde databestanden. Een ander onderdeel is de beschrijving van de watervalanalyse die wordt uitgevoerd in de analysefase, en uiteindelijk een beschrijving van de analyse van het totale model Testplan Daar waar het analyserapport gaat om de inhoudelijke resultaten en plausibiliteit, gaat het testplan en testrapport om de kwaliteit van de code. Het testplan beschrijft de testfilosofie, te gebruiken methodes en tools en beschrijft per module welke cases getest zullen worden. Deze testcases geven een duidelijke beschrijving van de bij de test te doorlopen stappen, welke testdata daarbij gebruikt wordt en wat het beoogde resultaat van de test is. Ook worden hierin de acceptatiecriteria vastgelegd. Ook voor de integratietesten met betrekking tot de volledige integratie van het nieuwe model moeten testcases worden beschreven met daarin te doorlopen stappen, gebruikte data en beoogd resultaat. Het testplan wordt voor opgesteld voordat de tests worden uitgevoerd. Dit betekent dat het testplan in delen geschreven zal worden, steeds voor de oplevering van aangepaste of nieuwe code. Pagina 13 van 15

14 Als uitgangspunt moet de JSTD-16 standaard gebruikt worden, op basis waarvan in overleg met RWS de vormgeving en inhoud van het document moet worden vastgesteld Testrapporten De resultaten van de in het testplan beschreven tests worden toegelicht. Hierbij moeten eventuele problemen bij het doorlopen van de voorgestelde cases worden beschreven, en de uitkomst van de testen. Als de uitkomsten niet overeen komen met de verwachtingen, moet dit gerapporteerd worden, en moeten vervolgens de nodige aanpassingen worden uitgevoerd en beschreven. Hierna moeten de tests herhaald worden, en nogmaals beschreven in het testrapport. Het testrapport moet gedurende het project per onderdeel worden aangevuld. Als uitgangspunt moet de JSTD-16 standaard gebruikt worden, op basis waarvan in overleg met RWS de vormgeving en inhoud van het document moet worden vastgesteld. 2.4 Hoofddocumentatie gebruikersinformatie Gebruikers handleiding Bij de nieuwe versie van BasGoed hoort een nieuwe gebruikershandleiding. Deze beschrijft hoe een gebruiker BasGoed kan installeren, toepassen en waar de eindresultaten te vinden zijn. Mogelijkheden voor het aanpassen van invoer en parameters moeten beschreven worden. Hierbij gaat het om parameters in de GUI, maar ook om aan te passen invoertabellen voor bijvoorbeeld kosten of productsamenstelling. De huidige gebruikershandleiding kan als basis gebruikt worden Toepassingsbereik In het toepassingsbereik van BasGoed moet beschreven worden wat het model wel en niet kan, en voor welke toepassingen het dus geschikt is. Voor het LMS/NRM wordt dit document in 2017 opgesteld. Een voorlopige versie van dit document is bijgevoegd bij deze uitvraag als achtergronddocument. Voor BasGoed dient een vergelijkbaar document opgesteld te worden Kaders Er is nog geen kader voor het gebruik van BasGoed. In 2017 wordt door RWS-WVL wel gewerkt aan het afstemmen van processen en uitgangspunten. Dit zal worden vastgelegd in een document, wat uiteindelijk zal moeten leiden tot een kader. Vanuit het project BasGoed 2018 moet een review uitgevoerd worden op het document/kader (afhankelijk van de status aan het eind van BasGoed 2018) waarbij aangegeven moet worden in hoeverre het aangepast moet worden aan de nieuwe versie van BasGoed. In het kader MKBA MIRT wordt BasGoed ook genoemd. Hierin moet ook worden aangegeven hoe het document moet worden aangepast aan de nieuwe versie van BasGoed. Pagina 14 van 15

15 2.4.4 Leveringsvoorwaarden De leveringsvoorwaarden beschrijven onder welke voorwaarde BasGoed gebruikt mag worden voor verschillende toepassingen. Deze leveringsvoorwaarden worden in 2017 vastgesteld voor de huidige versie van BasGoed. Omdat de nieuwe versie van BasGoed misschien andere data gebruikt en hier dus andere voorwaarden kunnen gelden, moeten de leveringsvoorwaarden indien nodig herzien worden Aanvraagformulier In 2017 is het aanvraagformulier voor BasGoed opgesteld. Dit aanvraagformulier moet aangepast worden. Hierbij moet het geschikt worden gemaakt voor de nieuwe versie van BasGoed, en moet het mogelijk worden om alleen de prognoseresultaten op te vragen i.p.v. een complete levering Geheimhoudingsverklaring Voor het gebruiken van de gedetailleerde bestanden van BasGoed is een geheimhoudingsverklaring nodig. Deze wordt in 2017 opgesteld door WVL (een concept versie is al wel beschikbaar). Hoewel het niet waarschijnlijk is dat deze aangepast moet worden, moet toch een korte check hierop gedaan worden en eventuele wijzigingen worden doorgevoerd. Belangrijk is dat deze verklaring een onderdeel van de complete set documentatie vormt, en daarom in de standaard op te leveren documentatie wordt opgenomen. 2.5 Overkoepelende projectdocumentatie Projectverslag Het projectverslag bevat een beschrijving van het hele project. Hierin zien we graag de volgende onderwerpen terug: - Gevolgde werkwijze (totaal, per fase, per inhoudelijk onderwerp) - Resultaten van analyses/onderzoeken die voor de inhoudelijke onderwerpen gedaan hebben, maar die niet in het uiteindelijke model zijn opgenomen. Hiervoor is vaak geen logische plek in het analyserapport. Als dit zo is kunnen de opgestelde memo s worden opgenomen in het projectverslag. - Beschrijving mogelijke en gemaakte keuzes met argumentatie - Overzicht van de originele planning en de gehaalde planning, inzicht in de verschillen - Conclusies - Aanbevelingen volgende versie BasGoed - Evaluatie/procesmatige aanbevelingen Pagina 15 van 15