Tickets schrijven die een remote developer begrijpt

Een remote developer kan een ticket zonder call oppakken als erin staat waarom het nodig is, wat er na afloop anders werkt en hoe je ziet dat het klaar is. Ontbreekt een van die drie, dan gaat de developer gokken of wachten, en allebei kost dat meer tijd dan het schrijven van een goed ticket.

Ik werk als developer vanuit Servië in teams van klanten, en ik pak elke dag tickets op die iemand anders heeft geschreven. Op kantoor loop je even naar iemand toe als iets onduidelijk is, maar op afstand moet het in het ticket staan.

Wat er in een goed ticket staat

Dit wil ik als developer in een ticket vinden:

• waarom het nodig is en voor wie, in een of twee zinnen
• het gewenste gedrag, gezien vanuit de gebruiker
• acceptatiecriteria die je kunt controleren
• context, zoals het ontwerp, de plek in de code, eerdere tickets en de thread waarin het is besproken
• wat er bewust buiten valt

Beschrijf het gedrag en laat de oplossing zoveel mogelijk aan de developer. Heb je een voorkeur voor de aanpak, of is er een beperking, zet die er dan apart bij. Dan weet de developer wat vastligt en waar ruimte is.

Acceptatiecriteria die je kunt testen

Een acceptatiecriterium is goed als twee mensen het los van elkaar op dezelfde manier controleren. "De pagina laadt snel" haalt dat niet. "De lijst met 500 orders laadt binnen een seconde op de testomgeving" wel.

Maak de criteria concreet met voorbeelden. Bij een kortingsregel schrijf je op wat er gebeurt bij een order van 100 euro met 10 procent korting, en wat er gebeurt met een kortingscode die gisteren is verlopen. Zulke voorbeelden worden vaak meteen de testgevallen.

De vorm Gegeven/Als/Dan kan helpen, maar hoeft niet. Een lijstje met zinnen die je kunt afvinken, werkt net zo goed.

Context die jij hebt en de developer niet

Op afstand mis je de gesprekken bij de koffieautomaat en het klantgesprek waar het ticket uit voortkomt. Wat jij weet omdat je erbij was, moet in het ticket, zoals wat een klant precies vroeg, een afspraak met een andere afdeling of een eerdere oplossing die niet werkte.

Een schermafbeelding van het probleem of een korte schermopname scheelt vaak een alinea uitleg. Gebruik wel testdata of geanonimiseerde voorbeelden. Persoonsgegevens uit productie horen niet in een ticket, ook niet op een schermafbeelding. Dat is een AVG-kwestie, en een ticketsysteem heeft meestal veel meer lezers dan je productiedatabase.

Link naar de plek in de code als je die weet. "Zie de kortingslogica in de checkout" laat iemand zoeken, terwijl een link naar het bestand jou een paar seconden kost.

Een definition of ready

Een definition of ready is een korte lijst waaraan een ticket voldoet voordat het de sprint in gaat. Houd hem kort, anders wordt het een formulier dat niemand invult. Zo'n lijst is genoeg:

• het waarom en de acceptatiecriteria staan erin
• ontwerp en teksten zijn klaar, als het om de interface gaat
• afhankelijkheden van andere teams of externe partijen zijn bekend
• het team heeft het besproken en een schatting gegeven
• het past in een paar dagen werk

Is een ticket niet ready, dan gaat het niet de sprint in. Dat voelt streng, maar een half uitgewerkt ticket in de sprint betekent dat de vragen midden in de sprint komen, als iemand er al aan begonnen is.

De juiste grootte

Een ticket dat langer dan een week duurt, is meestal te groot. Splits het in stukken die elk iets werkends opleveren, bijvoorbeeld eerst één kortingstype van begin tot eind en daarna de andere. Een splitsing in "backend" en "frontend" helpt weinig als geen van beide stukken los iets oplevert.

Een ticket als "refactor de orderservice" heeft geen eindpunt. Schrijf erbij wat er na afloop beter is, bijvoorbeeld dat de prijsberekening los te testen is.

Te kleine tickets zijn ook lastig. Tien tickets van een half uur die allemaal dezelfde context nodig hebben, kun je beter samenvoegen.

Voordat de developer begint

De developer heeft hier zelf ook een rol in. Voordat ik begin, zet ik in een comment hoe ik het ticket ga aanpakken en wat ik aanneem. Dat kost vijf minuten, en wie het ticket schreef, ziet meteen of we hetzelfde bedoelen.

Mijn advies aan opdrachtgevers is om tickets vóór de sprint samen met de developers door te lopen. In een remote team is die refinement de plek waar vragen bovenkomen voordat iemand er twee dagen aan heeft gewerkt. Hoe je de vragen daarna afhandelt zonder steeds te bellen, staat in async werken: wat schrijf je op.

Een voorbeeld: de verlopen kortingscode

Dit ticket kan ik zonder call oppakken:

Titel: Verlopen kortingscode geeft een duidelijke foutmelding

Waarom: klanten met een verlopen code zien nu "ongeldige code".
Ze moeten zien dat de code verlopen is, zodat ze niet denken
dat ze een typfout hebben gemaakt.

Gedrag: bij een verlopen code toont de checkout "Deze code is
verlopen op [datum]". Andere ongeldige codes houden de huidige melding.

Acceptatiecriteria:
- code die gisteren is verlopen: melding met de datum van gisteren
- code die nooit heeft bestaan: huidige melding "ongeldige code"
- geldige code: korting wordt toegepast zoals nu

Context: de validatie zit in checkout/discount.ts, de teksten in
de vertaalbestanden (nl en en). Gebruik de bestaande foutstijl.

Buiten scope: verlopen codes automatisch opruimen.

Het ticket is klein, maar een developer die het product niet kent, kan er meteen mee aan de slag. Zo'n ticket is ook een goede eerste taak voor een nieuwe developer, zie een remote developer onboarden.