Før en beslutningslogg i Jira: husk hvorfor dere valgte denne tilnærmingen

Seks uker etter en utgivelse spør noen hvorfor teamet valgte e-postvarsler i stedet for et daglig sammendrag. Jira-sakene forklarer hva som ble bygget. En kommentar sier «avtalt under planlegging». Personene som husker diskusjonen har det travelt, og ingen er sikre på hvilken begrensning som betydde mest.

En beslutningslogg fyller dette hullet. Den registrerer situasjonen, alternativene, valget og konsekvensene på et sted teamet kan finne. Med Power Packs Decision Log ligger posten ved siden av en Jira-sak, nær arbeidet den forklarer.

Denne veiledningen følger et fiktivt kundeportalteam som skriver én nyttig post, kobler den til leveransen og vurderer den igjen når kundebehov endres.

Avgjør hva som fortjener en post

En beslutningslogg trenger ikke å fange hver samtale. Start med valg fremtidige kolleger med rimelighet kan stille spørsmål ved: en leveransetilnærming, en avhengighet, en utgivelsesgrense eller et bevisst kompromiss med konsekvenser utover én liten oppgave.

For portalteamet kvalifiserer varslingslevering. Valget av umiddelbar e-post former implementering, testing, støtteinstruksjoner og kundeforventninger. Teamet har vurdert alternativer og forventer å revurdere valget hvis meldingsmengden øker.

Å rette en skrivefeil i en knappetikett trenger derimot sannsynligvis ingen egen beslutningspost. Skillet er praktisk: vil forståelse av begrunnelsen hjelpe noen med å vedlikeholde, endre eller forklare resultatet senere?

Arkitekturbeslutningsposter, ofte kalt ADR-er, gir et nyttig forbilde. Michael Nygards opprinnelige artikkel beskriver korte poster som bevarer kontekst, beslutning, status og konsekvenser, og beholder erstattede beslutninger med en henvisning til det nye valget. Kilden er lenket nedenfor. Eksemplet vårt bruker denne enkle ideen på en leveransebeslutning i Jira.

Gi beslutningen et tydelig hjem

Velg Jira-saken som best representerer arbeidet valget påvirker. I eksemplet bruker teamet saken som koordinerer kundeportalvarsler. Den peker allerede leserne mot implementerings- og testarbeidet.

Fortell teamet hvor posten finnes. Power Packs Decision Log tilhører en sak, så etabler en enkel vane for å finne den. En merknad i koordineringssaken kan si at varslingsbeslutninger vedlikeholdes der. Hvis teamet har en separat prosjektoversikt, legg saken der gjennom vanlig prosess.

Unngå å spre kopier over flere saker og forvente at de holder seg like. Andre oppgaver kan henvise leserne til det valgte hjemmet. Eksporterte kopier er nyttige til diskusjon, men teamet bør vite hvilken post som viser gjeldende standpunkt.

Skriv konteksten før konklusjonen

Kontekst forklarer hvorfor spørsmålet finnes. Skill mellom fakta, begrensninger og antakelser, slik at en fremtidig leser kan se hvilken del som endret seg.

Portalteamet skriver: «Kunder trenger å vite når en støttehenvendelse endres vesentlig. Den nåværende tjenesten sender allerede e-post. Første portalutgivelse inneholder ingen innboks. Vi forventer at de fleste henvendelser har få kundesynlige statusendringer, men vi har ennå ikke målt varslingsmengden etter lansering.»

Avsnittet er mer nyttig enn «e-post er enklest». Det forklarer utgangspunktet og gjør en antakelse synlig. Det unngår også å hevde at e-post alltid vil være riktig kanal.

Legg til referanser til støttende undersøkelser der det passer. Hvis en teknisk utprøving påvirket valget, identifiser Jira-saken med funnene. Hvis kundetilbakemeldinger er viktige, oppsummer det relevante mønsteret uten unødvendig å kopiere privat informasjon inn i beslutningen.

Konteksten bør la en ny kollega forstå situasjonen uten å rekonstruere et helt møte. Behold detaljene som påvirker valget, og la uvedkommende diskusjon stå på opprinnelig sted.

Sammenlign reelle alternativer

En nyttig post viser hva teamet kunne ha gjort. Ta med alternativene som ble seriøst vurdert, med en ærlig fordel og ulempe for hvert.

Dette er illustrerende vurderinger for det fiktive systemet. Et annet team kan allerede ha en innboks eller sammendragstjeneste, noe som endrer sammenligningen helt. God beslutningsdokumentasjon gjør avhengigheten av kontekst synlig.

Ikke svekk forkastede alternativer bare for å få det valgte til å virke uunngåelig. Et sammendrag har en reell fordel: færre separate meldinger. Teamet velger det bort for denne utgivelsen fordi tid og implementeringsomfang betyr mer under de nåværende antakelsene.

Skill også mellom et alternativ og en egen beslutning. Om en kundes hele melding skal vises i en e-post, kan trenge egen vurdering. Å samle alle varslingsspørsmål i én post gjør det vanskelig å forstå hva som faktisk ble avtalt.

Beskriv valget og konsekvensene

Skriv beslutningen som en hel setning: «For den første portalutgivelsen sender vi en e-post når en støttehenvendelse har en vesentlig kundesynlig statusendring. Interne redigeringer utløser ingen melding.»

Forklar så hvorfor: «Dette bruker den eksisterende leveringskanalen og gir kundene raske fremdriftsoppdateringer, samtidig som utgivelsesomfanget holdes håndterbart.» Setningen beskriver begrunnelsen i eksemplet; den hevder ikke at e-post alltid er billigere eller mer pålitelig.

Konsekvensene fortjener like mye oppmerksomhet. Teamet trenger en felles definisjon av en vesentlig endring. Testingen må dekke gjentatte oppdateringer og duplikathåndtering. Kundestøtte må forklare hvilke hendelser som skaper meldinger. Kunder med aktive henvendelser kan fortsatt få mer e-post enn de ønsker.

En nyttig konsekvens leder naturlig til oppfølgingsarbeid. Registrer implikasjonen her og håndter så oppgaven i Jira. En beslutningspost bør hjelpe noen å oppdage hvorfor arbeid trengs, uten å bli en andre arbeidskø med konkurrerende statuser og ansvarlige.

Opprett posten i Power Pack

Åpne Power Pack på den relevante Jira-saken og bruk Decision Log (ADR Lite). Legg til en post med en tittel som navngir det faktiske valget, som «Bruk umiddelbar e-post for vanlige portalstatusoppdateringer».

Velg en kategori som passer teamets bruk, og start med Proposed mens resultatet fortsatt diskuteres. Legg til beslutningstakeren og beslutningsdatoen når valget er tatt. Feltet for beslutningstaker registrerer hvem som eier valget; å skrive inn et navn gjennomfører ikke en godkjenningsprosess.

Fyll inn konteksten, legg til alternativer med fordeler og ulemper, velg valgt alternativ og skriv konsekvensene. Hold innholdet forståelig for noen som ikke deltok i diskusjonen.

Legg til berørte Jira-nøkler der det er nyttig. Redigeringsfeltet godtar kommaseparerte saksreferanser som kan identifisere implementerings- og testsaker påvirket av beslutningen. Behandle dem som registrerte referanser; bruk Jiras vanlige lenkeprosess separat når dere trenger en saksrelasjon.

Gjennomgå den ferdige posten med de involverte. Kontroller at valgt alternativ og skrevet forklaring stemmer. Bekreft lagringstilstanden før kolleger skal stole på den siste versjonen, særlig hvis verktøyet viser en lokal eller frakoblet tilstand.

Bruk status for å gjøre standpunktet tydelig

Power Pack tilbyr Proposed, Accepted, Rejected og Superseded. Avtal hvordan teamet bruker dem, slik at en leser kan skille en idé som venter på beslutning fra et valg som allerede styrer leveransen.

Når Maya, produkteieren, tar varslingsbeslutningen, registrerer teamet datoen og merker posten Accepted. Statusen beskriver beslutningens stilling. Den beviser ikke at implementeringen er ferdig, at tester besto eller at utgivelsen er godkjent.

Det samme skillet gjelder Rejected. Hvis et forslag ikke tas i bruk, kan en kort forklaring spare neste person for å gjenta en undersøkelse uten å vite at den allerede er gjort. Bevar nyttige begrunnelser selv om ingen leveranseoppgave følger.

Vurder beslutninger igjen når antakelsene endres

Se for deg at portalen etter lansering utvides til kunder med mange aktive henvendelser. Kundestøtte melder at noen mottar flere vanlige e-poster hver dag. Det er ny kontekst, direkte knyttet til den opprinnelige antakelsen om lav meldingsmengde.

Teamet åpner den gamle posten før det foreslår en endring. Nå kan det skille en tidligere rimelig avveining fra spørsmålet produktet står overfor i dag. Den eksisterende beslutningen forklarer hvorfor umiddelbar e-post ble valgt; den forbyr ikke en bedre tilnærming under andre forhold.

Opprett en ny Proposed-post for et daglig sammendrag. Power Pack kan duplisere en post til en Proposed-post som utgangspunkt. Gå nøye gjennom hvert kopierte felt: gamle antakelser, datoer og konsekvenser gjelder kanskje ikke lenger.

Når det nye valget er akseptert, merk den tidligere posten Superseded og henvis til erstatningsbeslutningen i erstatningsfeltet. Behold den opprinnelige begrunnelsen lesbar fremfor å skrive den om som om teamet alltid hadde planlagt et sammendrag.

Dette er en dokumentasjonspraksis for teamet. Postene forblir redigerbare, så avtal å opprette erstatningsposter ved vesentlige endringer og bruke vanlig redigering til rettelser eller presiseringer. Ikke behandle loggen som et uforanderlig revisjonsspor.

Gjør posten nyttig i det daglige arbeidet

Bruk loggen når noen blir med i teamet, foreslår et redesign eller spør hvorfor en oppgave inneholder et uvanlig krav. Søk og filtrering kan hjelpe med å finne en post i sakens logg. Power Pack kan også eksportere Markdown i ADR-stil for gjennomgang eller en annen dokumentasjonsflyt.

Før en eksport deles, kontroller at den gjenspeiler den aktuelle posten og identifiser saken der teamet vedlikeholder den. Et nedlastet dokument er et øyeblikksbilde; fremtidige endringer i saken oppdaterer ikke en kopi som allerede er sendt andre steder.

Start med én beslutning teamet nylig tok og sannsynligvis vil vurdere igjen. Skriv konteksten, de reelle alternativene, valgt tilnærming og konsekvensene. Legg posten ved siden av Jira-arbeidet i Power Pack og be en kollega som gikk glipp av diskusjonen lese den. Hvis personen kan forklare hvorfor valget var fornuftig og hva som ville begrunne en endring, gjør loggen nytte.

• Michael Nygard: dokumentere arkitekturbeslutninger