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.
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.