pexels-photo-203218

Do’s en don’ts bij het maken van functionele documentatie

Dit is het laatste deel van mijn blogserie over functionele documentatie in Agile. In deze delen heb ik uiteengezet dat het maken van functionele documentatie je op veel verschillende gebieden helpt in alle fases van software ontwikkeling:

  • Voor de ontwikkelfase:
    • Stakeholders betrekken en ondersteunen in het formuleren van hun wensen
    • De scope en context van het systeem inzichtelijk maken
    • Belangrijke vragen op tijd beantwoorden
    • De duivel in de details onthullen
    • Aandacht voor non-functionals en architectuur
  • Tijdens de ontwikkelfase:
    • Het geheugen scherp houden
    • De juiste zaken op de juiste manier bouwen
    • De software op requirements testen
    • Kennisdeling ondersteunen
  • In de toekomst:
    • Impactanalyses maken
    • Beslissingen naslaan
    • Requirements managen en regressietesten uitvoeren
    • Software effectief gebruiken
    • Kennis borgen

De vorige delen kun je hier vinden:

Deel 1: Introductie tot de blogserie: Documenteer, juist als je Agile werkt!
Deel 2: Functionele documentatie vóór je bouwt
Deel 3: Documentatie als basis tijdens de bouw, juist als je agile werkt
Deel 4: Documenteer voor later, ook in Agile

Natuurlijk moet je altijd blijven oppassen dat je niet in de ‘Big Design Up Front’ valkuil valt. Daarom heb ik in dit deel een aantal do’s en don’ts op een rijtje gezet bij het maken en gebruiken van functionele documentatie.

Do’s en don’ts

De belangrijkste ‘do’: Zie documentatie nooit als middel ter vervanging van mondelinge communicatie, maar altijd als ondersteuning ervan. Nadenken, communiceren en nog eens nadenken leiden immers tot de beste analyses en designs. Verder geldt:

Doe het samen

  • Maak en onderhoud geen documentatie op een eiland, maar doe dit samen met je (business) stakeholders en het ontwikkelteam. Zoek de mensen op die worden geacht jouw documentatie te gebruiken en te lezen.
  • Pas je documentatievormen daarbij aan de wensen van je publiek aan. Blijf toetsen of zij nodig hebben wat je maakt in de vorm waarin je het maakt, en hoe dit beter kan. Is de documentatie bijvoorbeeld te veel, te weinig, niet het juiste, of te moeilijk gepresenteerd?
  • Zorg als organisatie dat de verantwoordelijkheid voor functionele documentatie expliciet is belegd, en stel eisen aan de kwaliteit ervan.

Eerst de hoofdlijnen en kapstok

  • Het doel van documenteren is niet het vaststellen van een contract. Maak dus geen complete lijst van wensen en eisen waar het systeem aan moet voldoen. Waterval heeft ons geleerd dat dit alleen maar tegen je gaat werken.
  • Besteed veel aandacht aan de doelen die stakeholders met het systeem willen bereiken (het ‘waarom’). Dit is namelijk de beste samenvatting van wat het systeem gaat leveren voor de business en voor gebruikers, en is een goede basis voor een discussie over de scope en functionaliteiten (het ‘wat’) van het systeem.
  • Denk op hoofdlijnen na over de scope en functionaliteiten (het ‘wat’) en leg dit vast. Focus daarbij op wat je nodig hebt om valide inschattingen te kunnen maken over de complexiteit, kosten en doorlooptijd van de ontwikkeling.
  • Gebruik deze hoofdlijnen om een kapstok te creëeren; een structuur voor je documentatie waaraan je alle details kunt ophangen. Persoonlijk vind ik het fijn om functionaliteiten op te hangen aan een procesmodel of use case diagram.
  • Leg non-functional requirements zo snel mogelijk op hoofdlijnen vast – deze zijn richtinggevend voor je architectuurkeuzes en verhogen de kwaliteit van je functionele requirements.
  • Leg indien nodig ook vast wat een systeem niet doet. Dit is soms erg belangrijk om de scope vast te stellen en verwachtingen te managen.

…Daarna de details

  • Werk de details daarna incrementeel uit, op volgorde van de op dat moment geldende prioriteit (just-in-time investigation). Plan je analyse- en documentatiewerk zorgvuldig: complexe requirements hebben meer analyse prioriteit dan simpele requirements, ook al worden de simpele requirements eerder gerealiseerd. Dit heeft alles te maken met de doorlooptijd van je analyse werkzaamheden.
  • Laat je niet verleiden om je te veel op het ‘hoe’ te focussen, maar ga het ook niet uit de weg. Bij complexe functionaliteit is er namelijk veel denk-, communicatie- en daarmee ook documentatiewerk nodig.
  • Accepteer dat je documentatie niet in één keer goed hoeft te zijn. Er geldt hier hetzelfde als voor software: lever, leer en pas aan, op iteratieve wijze. Het hoeft ook niet perfect te worden: goed is goed genoeg (just-enough).
  • Leg niet alle details altijd vast. Hoe meer details je vastlegt, hoe meer werk je je op de hals haalt in het bijwerken van de documentatie. Probeer te experimenteren en ervaring op te doen, want het is een kwestie van ervaring om door te krijgen welke details relevant zijn om vast te leggen.
  • Grote, complexe producten met een groot belang vragen om meer en gedetailleerdere documentatie dan kleine, simpele producten met weinig belang. Probeer hier de goede balans in te vinden.

Denk goed na voor je documenteert

  • Schrijf niet zomaar elk requirement op een kaartje (zoals een user story), maar denk na, communiceer en denk nog meer na. Documenteer de resultaten van dat proces.
  • Als het even kan, maak dan plaatjes en modellen. Want mensen zijn erg visueel ingesteld, en zien is onthouden.
  • Wees niet bang om templates en eerder werk uit de kast te trekken. Ga niet alles compulsief invullen en overnemen, maar gebruik het als checklist: waar moeten we ook alweer aan denken in deze situatie.
  • Vraag jezelf altijd bewust af of het maken van documentatie nodig is en of er geen betere alternatieven zijn, maar wees er tegelijkertijd van bewust dat je documentatie pas mist op het moment dat je het mist – en dan is het dus al te laat.

Houd het levend en interactief

  • Giet niets in beton, maar houdt documentatie levend door continu voortschrijdende inzichten te verwerken (in dit kader kan een Wiki erg handig zijn).
  • Zorg dat mensen weten te vinden wat je hebt vastgelegd, en geef ze de ruimte om het met je te bespreken. Als niemand vragen stelt, is dat een slecht teken en kun je het beste pro-actief de leden van het ontwikkelteam vragen of alles duidelijk is.
  • Gooi nooit documentatie over de schutting. Zorg dat degene die het heeft opgesteld ook betrokken is bij het gebruik ervan zodat vragen snel kunnen worden beantwoord en het snel aangepast kan worden indien nodig.
  • Als je een bijvoorbeeld een logisch gegevensmodel of wireframes hebt gemaakt, print deze dan uit en hang deze naast het Scrum board. Zorg dat mensen het zien en erover gaan praten.

Pas op

  • Gebruik geen user stories als functionele documentatie en als naslagwerk. Daar is het niet voor bedoeld en niet voor geschikt.
  • Pas op als je vooraf gemaakte documentatie gebruikt als naslagwerk, want er kunnen verschillen in zitten die tijdens de bouw zijn ontstaan. Betrouwbaarheid van documentatie is erg belangrijk als je het wilt gebruiken als naslagwerk.

Methoden en technieken

  • Wees niet bang om requirements management principes en technieken uit de kast te trekken. Deze kunnen erg waardevol zijn om effectief functioneel beheer, feasibility analyses en impact analyses uit te kunnen voeren.
  • Er zijn legio methoden, technieken en artefacten waarvan er altijd een aantal perfect passen bij een situatie – ook die uit het waterval tijdperk. Wees dus ook niet bang om bijvoorbeeld architectuurschetsen, business cases, procesmodellen, gegevensmodellen en wireframes vast te leggen.
  • Laat jezelf niet limiteren door bestaande methoden, technieken en templates; een free-format schets werkt vaak ook uitstekend.
  • Geef de Use Case 2.0 een kans in plaats van user stories. Ik ben er erg van gecharmeerd, en geloof dat het heel erg veel waarde kan bieden.
  • Als je op zoek bent naar meer documentatie methoden en technieken, dan vind ik agilemodeling.com een goede resource.

Hier eindigt het niet

Ongetwijfeld is deze lijst nog veel verder uit te breiden. Ik daag je dan ook uit om dit voor jezelf te doen. Na het lezen van deze blogserie en door terug te denken aan je eigen ervaringen met functionele documentatie, denk ik dat je tot waardevolle inzichten kunt komen. En deel deze vooral!

Dit was het laatste deel van deze blogserie. Ik hoop je te hebben geïnspireerd in mijn overtuiging dat goede functionele documentatie een belangrijke plek heeft in Agile software ontwikkeling. Tot de volgende blog!




Aantal
0
shares
0
0