In teams die Agile werken zijn gesprekken de belangrijkste manier om kennis over het te ontwikkelen product over te dragen. Deze teams kunnen in de verleiding komen om niet of nauwelijks te documenteren. Documentatie is immers geen spectaculair product om te tonen tijdens een demonstratie aan de klant. Toch heeft documentatie zeker toegevoegde waarde voor Agile teams. In deze post bespreek ik wat deze waarde is en geef ik suggesties waarmee teams wendbaar kunnen documenteren.

Documentatie heeft meerdere functies. Zo ondersteunt documentatie de gesprekken in Agile teams. Deze post gaat echter in op een ander functie van documentatie: het vastleggen van kennis voor de langere termijn. Alistair Cockburn, een van de grondleggers van het Agile gedachtegoed, verwoordt het zo: “When you are playing the software development game your secondary goal is to setup to play the next game”. Door de kennis opgedaan in het huidige spel vast te leggen, begin je het volgende spel met een voorsprong.

Een item op een product backlog is een prima middel om de gesprekken en de workflow van een team te ondersteunen, maar is slechte documentatie. Allereerst omdat het item uit beeld verdwijnt als het team het heeft gerealiseerd. Daarnaast omdat een item vaak maar een deel van de werkelijkheid laat zien. Een toekomstig beheerder of ontwikkelaar moet de specificaties dan afleiden uit meerdere items die soms overlappen of elkaar tegenspreken. Een vertaalslag is nodig om de waardevolle kennis uit deze tijdelijke producten te borgen.

Zeven aandachtspunten

1. Focus op de doelgroep en noodzaak

De Agile-werkwijze brengt een principe onder de aandacht dat geldt voor elke geschreven tekst: focus op de doelgroep en op de noodzaak. Inventariseer aan het begin van een project wie de belanghebbenden van een document zijn. Het team zelf is in ieder geval een belanghebbende. Documentatie garandeert de continuïteit van het team bij wisselingen in bezetting. De contactpersoon bij de klant (Product Owner) kan aangeven wie andere belanghebbenden zijn. Denk bijvoorbeeld aan de beheerders en redacteuren van een website.

Het is belangrijk dat het team achterhaalt welke documentatie de belanghebbenden minimaal nodig hebben. Daarvoor zal het team de gewoontes van de belanghebbenden moeten doorbreken. Een beheerder die gewend is om een beheerhandboek te ontvangen, zal daar bijvoorbeeld om vragen. Vraag dan door welke informatie de beheerder echt gebruikt en lever alleen die informatie op.

2. Documenteer beslissingen

Waardevolle informatie voor de toekomst is de motivatie waarom dingen werken zoals ze werken. Denk aan een toelichting op technische keuzes in een architectuurdocument. Of een overzicht van designkeuzes in een style guide. Net zo belangrijk is de toelichting op businesskeuzes. Deze informatie bevindt zich bijvoorbeeld in een e-mail, memo of een product backlog item. Verzamel deze informatie tijdens het project. Als de klant zijn beslissing in de toekomst wil heroverwegen, kan hij dat veel effectiever doen met de oorspronkelijke motivatie en data als input.

3. Documenteer op het laatst verantwoorde moment

Een onderdeel van Agile werken is documenteren uitstellen tot het laatst verantwoorde moment. Op dat moment heeft het team het beste beeld van de functionaliteit die de klant wil en weet het team welke documentatie daar bij nodig is. Een Agile team documenteert vaak pas nadat functionaliteit is gebouwd. Een gevolg van deze werkwijze is dat de documentatie meegroeit met een product. Agile documentatie krijgt dus nooit het stempel ‘definitief’.

4. Breng structuur aan

Een duidelijke structuur is essentieel voor deze manier van documenteren. Structuur maakt dat het team snel kan zien welke delen van de documentatie wijzigen. En structuur maakt de informatie toegankelijk voor de gebruikers. Streef naar één structuur voor alle informatie. Kies voor de structuur bijvoorbeeld de features van het product. Een feature van een e-commerce website is bijvoorbeeld “beheren winkelmandje”. Bij deze feature vindt de lezer dan de belangrijkste interacties, het visual design, de bedrijfsregels en het datamodel bijeen.

5. Kies een geschikte vorm

Volgens Scott Ambler moet een team streven naar één bron voor alle documentatie. Zo blijft de documentatie consistent en voorkom je overlap. In de praktijk is dit lang niet altijd mogelijk. Maar teams kunnen wel een deel van de documentatie centraal vastleggen. Een wiki, bijvoorbeeld confluence, is daarvoor een goede vorm. Andere informatie kan beter landen in de applicatie zelf, bijvoorbeeld als helpteksten bij de invoerschermen voor redacteuren.

6. Maak documenteren onderdeel van de werkwijze

Teams moeten niet alleen bedenken hoe ze gaan documenteren, ze moeten ook maatregelen nemen zodat ze gaan documenteren. De meest voor de hand liggende optie is documentatie onderdeel te maken van de Definition of Done. Een feature is dan pas af als de bijbehorende documentatie ook af is. Een document als item opnemen op het product backlog kan ook. Mike Cohn stelt voor dat een team dit doet als de opdrachtgever een document eist dat het team niet uit zichzelf zou produceren. Daarmee wordt de inspanning die het document kost voor de opdrachtgever inzichtelijk.

7. Houd documentatie levend

Een van de grootste uitdagingen is het bijhouden van documentatie. Gojko Adzic introduceert hiervoor het concept levende documentatie als onderdeel van de Specification by example-aanpak. Adzic stelt voor dat een team de werking van een product documenteert met voorbeelden. Bijvoorbeeld: “Gegeven dat ik geen producten in mijn winkelmandje heb, als ik probeer af te rekenen, dan krijg ik een foutmelding”. Voorbeelden zijn goed leesbaar en ze zijn een basis voor automatische tests. Een team dat test met de voorbeelden uit de documentatie controleert in een keer de werking van de software en de juistheid van de documentatie. Zo blijven documentatie en werkelijkheid in overeenstemming.

In de vorige zeven aandachtspunten spreek ik over “het team” dat documenteert. Documenteren is dan ook de verantwoordelijkheid van het hele team, niet van een specifieke rol. Wel zal de bijdrage die elke rol levert verschillen: een software architect zorgt voor de top level architectuur, een visual designer voor de style tiles en een software engineer voor de API-documentatie. De business analist in een team levert de functionele beschrijving en kan de structuur en de onderlinge samenhang van de documentatie te bewaken.

Laten we als team wendbare documentatie maken die zo spectaculair is dat we het graag aan de klant tonen tijdens een demonstratie.