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