Mijn 5 belangrijkste agile documentatietips

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 het ontwikkelteam. 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 het ontwikkelteam) 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 ontwikkelteam 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 Agile requirements tot op het gewenste niveau uitwerken 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, requirementstechnieken expert
Nicole de Swart

Nicole de Swart

Nicole de Swart

Auteur Handboek Requirements

Volg Nicole op:

Priya Soekhai

Priya Soekhai

Expert agile samenwerken

Volg Priya op:

Tips voor de moderne analist

Je ontvangt eens per maand een nieuw artikel. Net zoals meer dan 5.000 collega abonnees.

Copy link