Met de komst van agile zijn we heel anders tegen documentatie aan gaan kijken. Vroeger is ons geleerd dat we alle requirements juist, volledig en eenduidig moesten vastleggen. We hadden het toen over SMART requirements.

Vastleggen van requirements was cruciaal omdat de documenten fungeerde als contract. En ze golden als basis voor de andere disciplines zoals projectmanagement, ontwerp, bouw, test en beheer.

Tips voor het opstellen van requirements­documenten

Tegenwoordig ziet het ontwikkelproces er anders uit. En is het niet meer vanzelfsprekend om alles te documenteren. Voor analisten met een traditionele achtergrond is dit een hele omslag.

Vragen die ik vaak krijg zijn:

  • Hoeveel informatie moet ik vastleggen?
  • Gaat er geen essentiële informatie verloren als ik niet alles vastleg?
  • Wanneer leg ik welke informatie vast?

In dit artikel deel ik graag de belangrijkste tips die ik dan geef.

1. Documenteer selectief

Vraag je steeds af hoe de informatie het beste overgedragen kan worden, mondeling of schriftelijk. Dan krijg je een goede mix van mondelinge en schriftelijke communicatie.

Documentatie gebruik je bij uitstek om tijd te overbruggen. Dus voor informatie die over een tijdje ook nog van belang is. Verder gebruik je documentatie om mensen die niet bij de meeting aanwezig waren te informeren.

Agile maakt veel gebruik van de kracht van mondelinge communicatie. Voor het tot stand komen en delen van belangrijke informatie organiseer je bij voorkeur een meeting. Een meeting waarin alle betrokkenen participeren. Er zijn veel effectieve technieken (en Liberating Structures en Innovation Games) die je voor dit soort meetings kunt inzetten.

2. Verspil geen tijd aan het onderhouden van documentatie

Leg alleen informatie vast als iemand die informatie op korte termijn nodig heeft. (Systeem­documentatie is hierop de enige uitzondering – zie tip 5). Informatie die er niet is, kan ook niet wijzigen. Zo voorkom je dat voortschrijdend inzicht veel impact op je documentatie heeft.

Vroeger moesten we de totale set aan requirements nauwkeurig vastleggen. Ze moesten goedgekeurd worden voordat de bouw startte. Daardoor zat er veel tijd tussen het vastleggen en het implementeren van de requirements. De kans is dan groot dat documentatie ondertussen verouderd is.

Met een agile werkwijze stel je requirements just in time vast. Je ontdekt gaandeweg wat de echte behoeften van de business zijn.

3. Gebruik user stories niet als documentie­techniek

Als je requirements ‘voor het nageslacht’ wilt vastleggen, gebruik daarvoor dan use cases of een andere traditionele requirementstechniek. User stories zijn er niet voor bedoeld. En ze zijn er ook niet voor geschikt.

De beschrijving van een user story is niet meer dan een geheugensteun. Een reminder voor de mondelinge afstemming van vertegenwoordigers van de business en de ontwikkelaars. Het hoeft dan ook niet meer dan een summiere beschrijving is. Na de sprint, als de user story is gebouwd, is de geheugensteun niet mee nodig. De user story gooi je dan weg.

4. Stel het documenteren zo lang mogelijk uit

Niet alleen het vastleggen maar ook het achterhalen van requirements doe je zo laat mogelijk. Net voordat iemand (bijvoorbeeld het management of de ontwikkelaars) de informatie nodig heeft.

Dat impliceert dat je weet voor wie je de informatie vastlegt en waarvoor zij het gaan gebruiken. Vraag je dus altijd af of de informatie direct toegevoegde waarde heeft en voor wie. Doorgaans betekent dat dat je begint met hele globale requirements. Deze werk je gefaseerd en in een aantal detailslagen steeds verder uit.

5. Leg beheerdocumentatie tijdens de sprint vast

Maak expliciet onderscheid tussen systeem- en projectdocumentatie. Het agile team heeft requirements (meestal in de vorm van user stories) nodig om de juiste software te bouwen. Dit is projectdocumentatie.

Systeemdocumentatie maak je onder andere voor beheer en onderhoud. Daarvoor is inzicht in de functionaliteit en de opzet van het systeem nodig. Deze informatie kun je pas goed vastleggen nadat de software is gebouwd.

Traditioneel gebruikten we de requirements voor meerdere doeleinden. Dat klinkt efficiënt. Maar het heeft meer na- dan voordelen. Het resulteert bijvoorbeeld in omvangrijke documenten die voor meerdere doelgroepen bestemd zijn. Gevolg is dat er voor de meeste doelgroepen veel overbodige informatie in de documenten staat. En ze soms door de bomen het bos niet meer zien.

Gestelde vragen beantwoorden

Ik hoop dat je met deze tips zelf voor jouw praktijksituatie kunt beantwoorden ‘Hoeveel informatie je moet vastleggen?’ en ‘Wanneer je welke informatie vastlegt?’ Als je mijn hulp daarbij wilt, is het trainingsprogramma Daadkracht met agile requirements wellicht iets voor jou.

Wil je extra toelichting of heb je specifieke vragen, plaats dan hieronder een reactie. En ik probeer je vragen te beantwoorden.

Nicole de Swart

Misschien vind je dit ook interessant

11 reacties

  • Rik Manhaeve

    Naast beheersdocumentatie is er nog de eindgebruikersdocumentatie (wie die maakt laat ik even in het midden, de situatie zal dit bepalen). Deze eindgebruikersdocumentatie is traditioneel opgebouwd rond de functionaliteit van het systeem. Naar mijn menig is dit verkeerd. Maak een onderscheid tussen en generieke applicatie (bv e mail) en een specifieke applicatie (bv orderadministratie). Gebruikers zoeken niet naar functionaliteit maar naar hoe het systeem hen kan helpen bij het uitvoeren van hun taak. Wat zij nodig hebben is de functionaliteit in context van de taak.
    Doe dit echter stapsgewijs naarmate dat de informatie beschikbaar komt. Dus eerst de grote structuren (opgehangen aan processen taken), die het WAT aangeven en pas daarna de functionaliteit daarbinnen, die het HOE aangeeft.
    Elektronische documentatie maakt dit veel gemakkelijker omdat het principe van ‘progressive disclosure’ veel vlotter teo te passen is door het inbouwen (kruisverwijzingen op papier werken niet goed). Dus eerst wat de gebruiker doet (bv registreren van een order met daarin het identificeren van een klant en pas op een lager niveau hoe je de klant identificeert). Dit laat de gebruiker toe te kiezen welke documentatie hij nodig heeft (enkel de taakgerichte informatie of ook de procedure).
    Agile laat toe de gebruikersdocumentatie stapsgewijze te ontwikkelen (de user story map in een top down benadering is hier een mogelijkheid). Doe niet alles in het begin, doe niet alles op het einde. In het laatste geval komt er dikwijls niet meer van

  • Otto K

    “Voor beheer en onderhoud is inzicht in de functionaliteit en opbouw van het systeem nodig.”

    Kun je hier nog iets meer over zeggen? Hoe ver raad jij aan te gaan met dit soort documentatie? Dat kan nog alle kanten op, van summier tot zeer uitgebreid. En wie heeft dat inzicht nodig?: beheerders, gebruikers, analisten, bouwers, testers? Ik denk (vrees) all of the above.

    “Daarom kun je pas nadat de software is gebouwd de juiste beheerinformatie vastleggen.”

    Ik geloof dat ik dit te kort door de bocht vind. In onze praktijk leggen we de beheerinformatie (vlak) voor de sprint vast. De beheerinformatie dient (bij ons) ook als expliciete beschrijving van wat er *precies* gebouwd moet worden en dus ook van wat er *precies* getest moet worden. Dat moet bij aanvang van de sprint duidelijk zijn. Het helpt enorm dat op te schrijven – naast het mondeling te bespreken. De beheerdocumentatie is preciezer en gedetailleerder dan de user story; de user story is zoals je zegt meer een geheugensteuntje die je weg zou moeten kunnen gooien nadat de user story is geïmplementeerd.

    Door met precisie op te schrijven kan je benodigde functionaliteit meer en makkelijker eenduidig maken dan je in een overleg (backlog refinement) kan bereiken. Het is een aanvulling op. Dat is wel mooi vind ik, vóór agile was het overleg de ‘aanvulling op’ 🙂 Mocht tijdens de sprint blijken dat iets toch anders moet worden dan passen we de beheerdocumentatie aan tijdens de sprint (of er vlak na). Dat is geen overbodig onderhoud maar de keerzijde van de “we welcome change” mentaliteit. Het is wel een mogelijk teken van te dunne backlog refinements.

    • Nicole de Swart

      Otto,
      Pas nadat de software is gebouwd kun je de JUISTE beheerinformatie vastleggen. Je legt in één keer de juiste informatie vast óf je past eerder vastgelegde beheerinformatie aan. Als je beheerdocumentatie niet voor andere doeleinden gebruikt, is vastleggen tijdens de sprint het best moment. Ik begrijp dat jullie user stories aanvullen met een precisie beschrijving van de benodigde functionaliteit, zoals we in waterval gewend waren. Als tijdelijke maatregel totdat de ontwikkelaars en testers de agile werkwijze onder de knie hebben, is dat prima.
      Beheerdocumentatie kan inderdaad alle kanten op. Hoe meer de organisatie is ingericht op agile werken hoe minder documentatie nodig is.

      • Otto

        “Ik begrijp dat jullie user stories aanvullen met een precisie beschrijving van de benodigde functionaliteit, zoals we in waterval gewend waren. Als tijdelijke maatregel totdat de ontwikkelaars en testers de agile werkwijze onder de knie hebben, is dat prima.”

        Leg je in agile geen precieze beschrijving meer vast? Volgens mij is dat niet gesteld in het Agile Manifesto. Afhankelijk van het project kan het zeer wenselijk zijn precies te beschrijven. Niet alleen voor de bouw en test op dat moment maar ook voor onderhoud (jaren) later. Het is vaak geen goede optie om code te lezen of “uit te proberen” om erachter te komen hoe het systeem werkt: een precieze beschrijving lezen is wel een goede optie. Deze noodzaak geldt met name voor systemen met veel interne beslislogica. In de verzekering- en pensioenbranche is dat core business.

        Of, hoe zie jij dit?

        • Nicole de Swart

          In agile leg je inderdaad geen precieze beschrijving meer vast. Reden is dat er betere manieren zijn om hetzelfde doel te bereiken.
          – Om te zorgen dat de juiste software wordt gebouwd, heb je in agile onder andere backlog refinement. Hierin stem je de benodigde informatie mondeling af met de ontwikkelaars. Als je backlog refinement goed uitvoert heb je aan een summiere beschrijving (als geheugensteuntje) genoeg.
          – T.b.v. beheer en onderhoud leg je meer vast, maar het is niet vanzelfsprekend om daarvoor (dikke) requirementsdocumenten te schrijven. Alleen de info die ze echt nodig hebben. Interne beslislogica valt daar al snel onder. Wat er bijvoorbeeld niet onder valt is alles dat je gewoon kunt zien als het systeem in productie is.
          Overigens maken ervaren agile teams hele inzichtelijke en onderhoudsvriendelijke code (want ze zijn als het ware iedere sprint opnieuw hun eigen code aan het onderhouden).

          • Maaike Groenewege

            Leuke discussie! Ik zie een Agile aanpak vooral als documenteren wat nodig is, niet meer, maar zeker ook niet minder. Dus als er behoefte is aan precieze beschrijvingen, is dat ook prima.
            Belangrijk daarbij: wie is je doelgroep, en wat is hun informatiebehoefte? Als je dat weet, zit je al een end in de goede richting.

  • Iris

    “De korte beschrijving van een user story is niet meer dan een geheugensteuntje voor de mondelinge communicatie die plaatsvindt tussen de business en het agile team.”
    M.i. worden user stories ook gebruikt bij het testen van de software.
    Punt 2 vind ik een interessante: volgens mij zou het zo moeten zijn dat bij een Agile werkwijze de inzichten gedurende een project kunnen wijzigen, maar dat de requierements daarom juist wel in een vroeg stadium vastgelegd moeten worden en ze continu bijgewerkt / onderhouden moeten worden. Dat niet alle behoeften van de business in een vroeg stadium duidelijk zijn, is 1 ding, maar het ontslaat de requirements-analist niet van het vastleggen van de requierements -> het agile team met ontwikkelaars en testers heeft alle informatie – ook in het begin – hard nodig.
    Door dit punt ontstaat bij een agile team vaak verwarring: onder het mom van Agile ‘niets vastleggen’ werkt vaak handig in overleg met de business over wensen en eisen aan het systeem, maar niet handig t.o.v. het agile team dat moet starten met een – hopelijk toch solide – basis.

    • Nicole de Swart

      Iris,
      User stories (met hun acceptatiecriteria) worden idd ook gebruikt voor het testen van de software. Ook dan is het niet volledig uitgeschreven, maar een geheugensteuntje van wat er besproken is.
      Heb je je weleens afgevraagd hoe solide de basis is als het gebaseerd is op requirements die nog gaan wijzigen? Ervaren agile teams laten de softwarearchitectuur sprint na sprint uitgroeien.

  • Frans

    User stories bewaar ik altijd, omdat hierin in kort en bondige taal het DOEL van bepaalde functionaliteit staat beschreven. Altijd handig om achteraf en/of later eenvoudig antwoord te geven op de waarom vraag. Uiteraard bevat een user story niet alle details. Die leg je vast in bijvoorbeeld use cases.

  • Ulrich

    Ik ben bezig met kennisoverdracht aan een nieuwe product owner en een nieuwe supportorganisatie. Hoe vind ik de juiste balance tussen documentatie (weinig voorhanden) en meetings om de visie en de juiste aanpak over te brengen? Documentatie schrijven kost veel tijd en ik ben bang dat niemand ze leest.

    • Nicole de Swart

      Goede vraag, Ulrich. Sowieso heel goed dat je je het afvraagt en niet als vanzelfsprekend gaat documenteren.
      Het is inderdaad zoeken naar een balans, en die is van heel veel factoren afhankelijk. Gelukkig hoef je het niet allemaal zelf te bedenken. Vraag vooral aan de nieuwe PO en medewerkers van de supportorganisatie wat voor info zij nodig hebben (en waarvoor). Stel dan samen al doende een mix samen. Onderdeel daarvan kan bijvoorbeeld ook zijn dat jij nog een tijdje bereikbaar blijft voor vragen/overdracht op het moment dat ze ergens tegenaan lopen.

Geef een reactie