Managed hosting door True
Deze opinie is van een externe deskundige. De inhoud vertegenwoordigt dus niet noodzakelijk het gedachtegoed van de redactie.

Documentatie blijft altijd nodig

 

Computable Expert

drs. Gert Jan Timmerman
Manager Kenniscentrum, Info Support. Expert van Computable voor de topics Infrastructuur, Security en ICT-branche.

Bij Agile-systeemontwikkeling wordt niet veel aandacht besteed aan het schrijven van documentatie. Schrikbeelden uit het verleden van stapels documentatie die nooit geraadpleegd werd, is een belangrijke oorzaak hiervan. Maar schieten we niet te ver door? Gaan we er niet te gemakkelijk vanuit dat we geen documentatie nodig hebben?

Tegenwoordig wordt veel software ontwikkeld volgens een Agile-methodiek, zoals Scrum. Eén van de onderliggende principes van Agile-softwareontwikkeling is: ‘we value working software over comprehensive documentation’ (manifesto for Agile software development). Dat betekent natuurlijk niet dat er geen documentatie meer gemaakt moet worden, maar dat we niet meer tijd willen besteden aan het schrijven van documentatie dan strikt noodzakelijk is.

Dat brengt ons bij de volgende vraag: welke documentatie hebben we minimaal nodig en hoe zorgen we ervoor dat we voldoende tijd besteden aan het schrijven van deze documentatie? Het antwoord op deze vraag is niet eenvoudig te geven en dat leidt er in de praktijk vaak toe dat er vaak te weinig documentatie gemaakt wordt.

Als er al documentatie gemaakt wordt, gaat het vaak om ontwerpdocumentatie (use cases, class diagrams die bij het ontwerpen van de software gebruikt zijn). Het is de vraag of dit geschikte documentatie is, omdat de kans aanwezig is dat de software die gebouwd is, niet volledig gebouwd is volgens de gemaakte ontwerpen, bijvoorbeeld omdat er in een later stadium toch nog wat wijzigingen waren of doordat bleek dat er in het ontwerpstadium nog geen volledig beeld bestond van wat er precies gebouwd moest gaan worden. Zeker bij iteratieve methodieken (bijvoorbeeld Scrum) wordt in elke iteratie een stukje functionaliteit gebouwd, maar meestal wordt niet in elke iteratie de ontwerpdocumentatie bijgewerkt of aangevuld.

Door aan het eind van een project alle geproduceerde ontwerpdocumentatie op een hoop te vegen en er de sticker ‘Systeemdocumentatie’ op te plakken, lopen we het risico dat we documentatie opleveren die niet overeen komt met de opgeleverde software. Dergelijke documentatie heeft geen toegevoegde waarde, sterker nog, het wekt de indruk dat er documentatie is, terwijl dat niet het geval is.

Als we serieus software willen ontwikkelen volgens Agile-principes, zullen we van tevoren moeten vaststellen welke documentatie we minimaal nodig denken te hebben om het systeem in de toekomst te kunnen onderhouden en doorontwikkelen. Die documentatie hoort op de sprint backlog te staan en als onderdeel van het project opgeleverd te worden. We zullen ervoor moeten zorgen dat die documentatie actueel is en een correcte beschrijving is van het gebouwde product. Als we dat niet doen, verhogen we wellicht onze velocity, maar schuiven we de rekening naar de toekomst.

Dit artikel is afkomstig van Computable.nl (https://www.computable.nl/artikel/5159708). © Jaarbeurs IT Media.

6,3


Lees meer over


 

Reacties

Absoluut mee eens.

Te vaak heb ik systeemwijzigingen moeten doorvoeren zonder voldoende documentatie. Het kost zoveel meer tijd om dan uit de code terug te lezen wat er veranderd moet worden. En het risico om iets te missen is niet denkbeeldig.

Misschien is het goed om meer tijd in een handleiding te steken en deze te annoteren met de redenen waarom iets zo gebouwd is voor de ontwerper. De "thin version" kan dan naar de gebruiker en de "thick version" is voor de ontwerper. Wellicht dat dit ons uit het dilemma kan helpen.

@GertJan Goed artikel en blij dat je de documentatie nog even onder de aandacht brengt. Inderdaad heel zorgelijk dat er in dat Agile manifesto deze stament 'werkende software boven documentatie' staat, dat zet de mensen niet op het goede spoor en ga je haast nog denken, documentatie is niet zo belangrijk. Terwijl hoe weet je nu of je software werkt als je geen gedocumenteerd referentiepunt hebt?

Vraag is dan welke documentatie er nodig is? Je kan er zo al een aantal bedenken, requirements document, functionele specs, technisch ontwerp, gebruikers handleiding, operationele handleiding. Allemaal uit de oude doos maar heel voor de hand liggend. Hoeven geen uitgebreide epistels te zijn als het maar bestaat en het juiste op papier staat.

Tsja, en Scrum. Scrum zegt in principe niets over de inhoud en richt zich vooral op het proces. Hoe houd ik de gang erin en is het ook controleerbaar? De Scrum processbegeleidings methode zegt niets over bijvoorbeeld documentatie. Nou ja, niet helemaal, het proces in de vorm van een grote todo lijst en een 'productowner' uit de bussiness die zegt wat er nu weer gebeuren moet. Je mag er maar op hopen dat scrummmers van dienst het besef hebben wat de juiste deliverables an een project horen te zijn. Mijn grote kritiek op Scrum, het gaat over het proces, niet over inhoud en de verkeerde dingen worden belangrijk gemaakt.

Die vraag om documentatie hoeft niet te vloeken met Agile want net zoals onzekerheid en voortschrijdende inzicht constanten zijn bij softwareontwikkelingen geld dat ook voor je documentatie. Het bouwt zich op.

Goed dat dit stuk geschreven is en kan me er in vinden.

Dan heb je ook nog de vragen, documentatie voor wie? Andere techneuten die in de toekomst verder moeten bouwen? Documentatie voor de eindgebruiker? En waar moet die documentatie terecht komen? En waar in de documentatie moet de nieuwe documentatie terecht komen? Documentatie wordt namelijk vaak een rommeltje als het door de tijd heen aangevuld wordt. Van elk item bestaat er namelijk meer dan 1 stukje documentatie...

Kortom, het is gewoon best ingewikkeld :-)

Documentatie wellicht als onderdeel van elke sprint item.

En wie documenteert de zaken bij de unit tests? En waar komt die terecht?

Je laatste zin over technische schuld is een rake!

De vraag is voor wie je de documentatie maakt.

Voorkomen van technical debt is een hele belangrijke, vooral in sectoren waar de sofware een lange levens- en onderhoudsduur heeft.
Maar er zijn ook een aantal sectoren waar je verplicht van alles vast moet leggen om te voldoen aan regelgevingen etc..

Agile ontwikkelen kan nog steeds, waarbij je je documentatie gewoon onderdeel maakt van je "deliverables". Hierbij moet overigens ook opgelet worden dat je de documentatie niet achteraf maakt. Het is namelijk heel lastig uit te leggen aan een auditor dat je designdocumentatie pas geauthorizeerd was nadat je het product al getest had.

Het lullige is alleen dat deze "must have" documentatie soms haaks staat op het genoemde manifesto, in die zin dat het uitbrengen van een nieuw feature misschien 100 regels code met zich meebrengt, maar tegelijkertijd een hele stapel documenten.
Dit los je niet op met Agile of welke andere methodiek dan ook. Wil je alleen software maken en geen stapels documenten, dan moet je niet voor zwaar gereguleerde sectoren kiezen.

Uitstekend artikel waar ik mij erg in kan vinden.
Mijn indirecte colega's die in tegenstelling tot ikzelf keurig volgens scrum dinges werken houden keurig hun documentatie bij en er wordt wel degelijk gebruik van gemaakt.

Ikzelf hou van alles wat ik doe ook documentatie bij die ik notabene zelf regelmatig raadpleeg.
Sterker nog, gewoon in diverse mappen op papier uitgedraaid,
Want als er ergens netwerk issues zijn wil ik documentatie bij de hand hebben, en niet hoeven te panieken omdat een server niet bereikbaar is.

Ik heb helaas maar al te vaak ervaren dat documentatie niet deugt omdat het gewoon niet bijgehouden wordt.
Een belangrijke reden is dat er tegenwoordig in de dotNiet en php wereld veel gebruik gemaakt wordt van allerlij frameworks waarvan de developer geen flauw idee heeft wat het doet.
Gevolg de documentatie bijvoorbeeld over een API klopt niet.

Het feit dat een klant niets ermee doet is nog geen reden om de zaak niet goed bij te houden !
De klant betaalt ook daar voor !

Termen als "Documentatie" en "beschrijvingen" associeren al snel met old-school. Dikke word documenten, ergens opgeslagen, met een filenaam waruit je moet begrijpen wat er mogelijk in staat, en die niemand opent en leest.
Belangrijk is actualiteit en online toegankelijkheid. De beste manier van "Agile" documenteren vind ik de wiki aanpak. Voorbeeld: het all-the-way gebruiken van Atlassian's Confluence ,i.c.m andere tools van ze. Dan wordt documentatie een website met klikbare plaatjes, teksten en info die uit de runtime wordt opgehaald, online delen van de teksten met de gebruikers, feedback forms, etcetera. Dat werkt wel!

De grootste uitdaging bij documentatie is het onderhoud. Als je een aanpassing maakt of moet uitvoeren ben je er nooit meer zeker van of voorgaande aanpassingen goed in de documentatie terecht zijn gekomen dus dan toch maar de code langslopen.

@PaVaKe Voor wie en waarom maak je de documentatie? Ik denk bijvoorbeelds specificaties belangrijk zijn bij de communicatie tussen de gebruikers en bouwers en testers. Verreweg te prefereren boven het productowner model wat mij betreft. Of je (nieuwe) collega's wegwijs te maken, of gebruikers en beheerders van de juiste informatie te voorzien. Maar ook wat je schrijft, vereist vanuit regelgeving. Voldoende goede redenen lijkt me.

Eens met hier geschreven, lastige is het bijhouden van de documentatie en het risico op al die documenten met die vele namen en al die directories op de project schijf. @Michiel Het Wiki model lijkt me een mooie maar de uitdaging zit er naar mijn mening in hoe bepaal je welke type documentatie er moet zijn en vooral niet meer dan dat en toch dekkend.

Leuk artikel en een interessant punt. Documentatie is voor mij onderdeel van de Definition of Done, zonder de juiste documentatie is een story niet af. Wat de 'juiste documentatie' is kan volgens mij het best in sprint 0 worden afgesproken. Let er op dat hierbij vertegenwoordigers van de eindgebruiker en beheer aanwezig zijn. Deze moeten voor zichzelf al hebben bedacht wat 'voldoende' documentatie is.

Door userstories conform INVEST op te stellen is de kans dat opgeleverde software -en daarmee documentatie- achteraf moet worden aangepast al een stuk kleiner. Als er een aanpassing op functionaliteit uit een vorige sprint is, zal dit een nieuwe userstory worden die ook weer aan de DoD moet voldoen. Hier valt dus ook weer bijgewerkte documentatie onder.

Eens met de noodzaak voor documentatie, maar de link naar agile en scrum raakt kant noch wal.

Het agile manifest geeft aan dat werkende software belangrijker is dan uitgebreide documentatie. Er wordt nergens gezegd dat documentatie niet belangrijk is. Ik vind dit een prima principe; documentatie is belangrijk (heel belangrijk), maar uiteindelijk gaat het om de werkende software.

Dat documentatie niet wordt bijgewerkt zegt helemaal niets over agile werken, maar over een gebrek aan discipline of een onduidelijke definition of done. Maak documentatie een onderdeel van je definition of done. Een nieuwe functionaliteit of wijziging van bestaande functionaliteit is pas 'done' zodra het ontwikkeld, getest en gedocumenteerd is.

@Louis, de ideale manier voor delen van user specificaties zijn user stories. En die kun je goed kwijt in een dynamisch systeem (bijv Jira), waarmee je naar die users, en naar andere stakeholders kunt communiceren die geinteresseerd zijn in voortgang e.d.

De truuk is om documentatie niet als iets extras te zien, maar als onderdeel van je deliverables. Je moet dan eerst een lijstje van je doelgroepen en use cases maken. Dan formuleer je de doc requirements als stories. Voorbeeld: "als operator wil ik een beschrijving hebben van de methode om een nieuwe versie live te brengen". Dan valt het op z'n plek: die stories worden dan gewoon deliverables die je in je sprints meeneemt.

Nix doc, only stories. In beetje Agile/Scrum/Lean loopt de toekomst tot het eind van de huidige sprint. Na de demo noem je het product gewoon legacy en laat je wat nieuws bouwen door young talent.

@The Cat. Ja (Yes), nieuw is altijd beter, hoe dan ook, sowieso (German).

Goed idee om de gebruikers van de systeemdocumentatie te betrekken in het ontwikkeltraject zodat de vereisten daaraan ook inzichtelijk worden? Devops model lijkt mij een oplossing in gevallen waar dat mogelijk is.

Volgens mij draait het allemaal om de dialoog: met de mensen die de documenten gaan gebruiken (en die ze nu dus missen). Die mensen moeten aangehaakt worden en daarmee ook invloed krijgen op de vorming van de Product Backlog.

Overigens heb ik ook van een software leverancier gehoord die al jaren specialistische documentalisten in dienst had, maar die pas echt effectief werden toen zij deel uit gingen maken van de Scrumteams. Niet alleen doordat ze dat documenteerden wat er ontwikkeld werd, maar ook doordat ze door hun brede algemene kennis van het gehele (!) pakket waarde toevoegden in de ontwerpdiscussies binnen het team :)

"...om het systeem in de toekomst te kunnen onderhouden..."

Dit is een al jaren lopende discussie welke eind jaren 90 op usenet startte als gevolg van alle nieuwe ontwikkeltalen en methodieken en resulteerde in compleet verschillende opvattingen zoals de code is de documentatie en vice versa. Want als het om documenteren gaat dan speelt helaas toch vaak: 'Uit het oog, uit het hart' mee waardoor er al snel een 'cognitieve dissonantie' ontstaat tussen de software en alle daarbij behorende beschrijvende teksten.

Over agile en (S)CM is dan ook al een heleboel geschreven want de discussie gaat nog steeds door alleen nu op allerlei fora. Tenslotte dient documentatie zich niet alleen tot onderhoudbaarheid van de code te beperken maar de beheersbaarheid van een systeem als geheel te garanderen. Ik zal dus maar niets zeggen over alle ongedocumenteerde features in software;-)

@MichaelSteltman Eens dat documentatie net zoals de opgeleverde systemen een van je deliverables zijn maar ik twijfel of user stories nu de manier voor het delen van documentatie zijn. Dan zie ik zelf liever benoemde documenten die door je project heenlopen en zich ontwikkelen, de voorbeelden die ik noemden. En niet je project als een aaneenschakeling van user stories. Dat je in een sprintje als taak aandacht aan die documentatie geeft lijkt begrijpelijk. Documentatie is zelden af. Tsja, dat manifesto, hoe kan je het verzinnen!

@MaartenvanderLee De statement in het manifesto over documentatie, daar kan je vele kanten mee op ben ik inmiddels wel achtergekomen. Het is ook een dwaze statement 'werkende software boven documentatie' en gaat nergens over, alsof dit een afweging is. Als het er om gaat om verplichte zinloze documentatie als onderdeel van de projectbureaucratie dan kan ik het begrijpen, maar natuurlijk is documentatie nodig ook om te bepalen of je software werkt. Al zal het al gezegd afhangen voor het soort project.

Documentatie hangen aan wat er tijdens een sprint wordt gedaan lijkt me eigenlijk niet zo relevante documentatie. Of het moet je gaan om de voortgang en het controleren van activiteiten. Ik doel meer op de documentatie die beschrijvend is, om te weten wat er gemaakt moet worden of voor de communicatie naar buiten. Al valt dat bijhouden niet mee.

Rozen verwelken, schepen vergaan, de noodzaak om documentatie bij te houden zal altijd blijven bestaan.
Iedereen mag er wellicht een hekel aan hebben maar zo lang we (gelukkig) nog geen letterlijke brain dumps kunnen maken zul je een manier moeten gebruiken om kennis op te slaan om die over te kunnen brengen.
Ook als je na 10 jaar vergeten bent wat je ook al weer gemaakt had.

Johan,
Precies om die reden maak ik altijd uitvoerige documentatie en doe ik dat lopende het project.

Ik ontwikkel volgens het fire and forget princype.
Dus ik bak code, neem daar de tijd voor. Zorg dat het resultaat goed werkt en goed getest wordt, pas eventueel dingen aan of poets hier of daar nog wat op.
Daarna interesseert het project mij geen bal meer en ga ik wat anders doen.
Over een half jaar weet ik echt niet meer wat ik gedaan heb en waarom.
Dan is een goed verhaal met je overwegingen, specs en uitwerking dus erg nuttig.
Zo'n document kun je ook over de schutting gooien en er een andere collega mee aan de slag laten gaan.
Nu ja.. tenminste als je net als ik collega's weet te vinden die enig niveau hebben.... die schijnen erg zeldzaam te zijn.

Wij doen overigens geen Scrum maar jbf.

Zelf heb ik bij diverse klanten implementaties gedaan van Agile/Scrum. Vanuit mijn werk als Scrum Trainer kom ik ook regelmatig situaties tegen waarin dit statement van het Agile Manifesto letterlijk gezien wordt als een excuus om niet meer te documenteren. In mijn trainingen zeg ik hier dan ook altijd dat je wel moet documenteren, maar alleen zaken die een waarde hebben. Dus documentatie waar iets mee wordt gedaan, 'Value is the Key'. Ik ben het dan ook zeker eens met feit dat het maken van documentatie een taak is die moeten worden gedefinieerd in elke sprint bij de rest van de taken, zoals bouw, test enz. Is dus een onderdeel van je DoD.

al die meningen... In Scrum is er maar 1 die bepaalt wat de deliverables zijn en of die nodig zijn : De productowner

Dat documentatie niet geheel up-to-date is, is niet nieuw. Hier hebben we ook last van bij traditionele systeemontwikkeling.

Maak elke partij die documentatie wil, zelf verantwoordelijk voor die documentatie. Dat lijkt goed te werken. En om ervoor te zorgen dat de kwaliteit van die documentatie op orde blijft, neem ik in de Definition of Done op dat de documentatie up-to-date moet zijn. Goed versiebeheer en tracebility is uiteraard een must in deze.

Vacatures

Stuur door

Stuur dit artikel door

Je naam ontbreekt
Je e-mailadres ontbreekt
De naam van de ontvanger ontbreekt
Het e-mailadres van de ontvanger ontbreekt

×
×