Mantingueu un registre de decisions Jira: recordeu per què heu triat aquest enfocament

Sis setmanes després d'un llançament, algú pregunta per què l'equip va triar les notificacions per correu electrònic en lloc d'un resum diari. Els tiquets Jira expliquen què es va construir. Un comentari diu "d'acord en la planificació". La gent que recorda la discussió està ocupada i ningú està segur de quina limitació importava més.

Un registre de decisions omple aquest buit. Enregistra la situació, les opcions, l'elecció i les seves conseqüències en un lloc que l'equip pot trobar. Amb el registre de decisions de Power Pack, aquest registre es troba al costat d'un tiquet de Jira, a prop del treball que explica.

Aquesta guia segueix un equip de portal de clients fictici mentre escriu un registre útil, el connecta amb el lliurament i el torna a visitar quan canvien les necessitats del client.

Decidiu què mereix un registre

Un registre de decisions no necessita captar totes les converses. Comenceu amb opcions que els futurs companys d'equip poden qüestionar raonablement: un enfocament de lliurament, una dependència, un límit d'llançament o un compromís deliberat amb conseqüències més enllà d'una petita tasca.

Per al nostre equip del portal, l'entrega de notificacions qualifica. L'elecció immediata del correu electrònic configura la implementació, les proves, les instruccions de suport i les expectatives dels clients. L'equip ha considerat alternatives i espera reconsiderar l'elecció si creix el volum de missatges.

Per contra, corregir un error ortogràfic en l'etiqueta d'un botó probablement no necessita el seu propi registre de decisió. La distinció és pràctica: entendre el raonament ajudaria algú a mantenir, canviar o explicar el resultat més tard?

Els registres de decisions d'arquitectura, sovint anomenats ADR, proporcionen un precedent útil. L'article original de Michael Nygard descriu registres breus que conserven el context, una decisió, l'estat i les conseqüències, conservant les decisions substituïdes amb una referència a la nova elecció. La font està enllaçada a continuació. El nostre exemple aplica aquesta idea lleugera a una decisió de lliurament Jira.

Doneu una llar clara a la decisió

Trieu el tiquet de Jira que millor representi el treball afectat per l'elecció. Per a aquest exemple, l'equip utilitza el problema per coordinar les notificacions del portal del client. Ja apunta els lectors cap al treball d'implementació i prova.

Digues a l'equip on viu el disc. El registre de decisions de Power Pack pertany a un tiquet, així que establiu un hàbit senzill per trobar-lo. Una nota al tema de coordinació pot dir que les decisions de notificació es mantenen allà. Si el vostre equip manté un índex de projecte separat, afegiu-hi el problema mitjançant el vostre procés normal.

Eviteu difondre còpies entre diversos problemes i espereu que es mantinguin alineats. Altres entrades poden dirigir els lectors a la casa escollida. Les còpies exportades són útils per a la discussió, però l'equip ha de saber quin registre consultar per a la posició actual.

Escriu el context abans de la conclusió

El context explica per què existeix la pregunta. Hauria de distingir fets, limitacions i supòsits perquè un futur lector pugui saber quina part ha canviat.

L'equip del portal escriu: "Els clients han de saber quan una sol·licitud d'assistència canvia de manera significativa. El servei actual ja envia correu electrònic. La primera versió del portal no inclou una safata d'entrada. Esperem que la majoria de les sol·licituds tinguin un petit nombre de canvis d'estat visibles pel client, però encara no hem mesurat el volum de notificacions després del llançament".

Aquest paràgraf és més útil que "el correu electrònic és l'opció més senzilla". Explica el punt de partida i fa visible un supòsit. També evita afirmar que el correu electrònic sempre serà el canal adequat.

Si escau, afegiu referències a la investigació de suport. Si un pic tècnic va informar de l'elecció, identifiqueu el tiquet de Jira que conté les seves troballes. Si els comentaris dels clients són importants, resumiu el patró rellevant sense copiar la informació privada innecessàriament a la decisió.

El context hauria de permetre que un nou company entengui la situació sense reconstruir una reunió sencera. Mantingueu el detall que influeix en l'elecció i deixeu la discussió no relacionada a la seva ubicació original.

Compara alternatives genuïnes

Un registre útil mostra el que l'equip podria haver fet. Incloeu les alternatives que s'han considerat seriosament, amb un avantatge i un desavantatge honestos per a cadascuna.

Aquestes són avaluacions il·lustratives d'aquest sistema de ficció. És possible que un altre equip ja tingui una safata d'entrada o un servei de resum, canviant completament la comparació. Una bona redacció de decisions fa visible aquesta dependència del context.

No debilitis les opcions rebutjades només per fer que la seleccionada sembli inevitable. Un resum té un avantatge real: menys missatges separats. L'equip opta per aquest llançament perquè el temps i l'abast d'implementació són més importants sota els supòsits actuals.

També distingiu una opció d'una decisió separada. Si s'ha de mostrar el missatge complet d'un client dins d'un correu electrònic pot requerir la seva pròpia revisió. Doblar totes les preguntes de notificació en una sola entrada fa que sigui difícil entendre què es va acordar realment.

Indica l'elecció i les seves conseqüències

Escriu la decisió com una frase completa: "Per a la primera versió del portal, enviarem un correu electrònic quan una sol·licitud d'assistència tingui un canvi significatiu d'estat visible per al client. Les edicions internes no activaran cap missatge".

A continuació, expliqueu per què: "Això utilitza el canal de lliurament existent i ofereix als clients actualitzacions ràpides del progrés alhora que manté l'abast de llançament manejable". La frase descriu la raó d'aquest exemple; no afirma que el correu electrònic sigui universalment més barat o més fiable.

Les conseqüències mereixen la mateixa atenció. L'equip necessita una definició compartida d'un canvi significatiu. Les proves han de cobrir les actualitzacions repetides i la gestió de duplicats. El suport ha d'explicar quins esdeveniments produeixen missatges. Els clients amb sol·licituds ocupades encara poden rebre més correu electrònic del que volen.

Una conseqüència útil porta naturalment a un treball de seguiment. Enregistreu la implicació aquí i, a continuació, gestioneu la tasca a Jira. Una entrada de decisió hauria d'ajudar algú a descobrir per què és necessari treballar sense convertir-se en un segon endarreriment amb estats i responsables competidors.

Creeu el registre a Power Pack

Obriu Power Pack sobre el tiquet rellevant de Jira i utilitzeu el registre de decisions (ADR Lite). Afegiu una entrada amb un títol que anomena l'opció real, com ara "Utilitzeu el correu electrònic immediat per a actualitzacions rutinàries d'estat del portal".

Trieu una categoria adequada a l'ús del vostre equip i comenceu amb Proposat mentre el resultat encara estigui en discussió. Afegiu el decisor i, quan es faci l'elecció, la seva data de decisió. El camp decisor registra qui és el responsable de l'elecció; introduir un nom no duu a terme un procés d'aprovació per a vostè.

Omple el context, afegeix les alternatives amb els seus pros i contres, selecciona l'opció escollida i escriu-ne les conseqüències. Mantenir el contingut comprensible per a algú que no va assistir a la discussió.

Afegiu les claus Jira afectades quan sigui útil. L'editor accepta referències de problemes separades per comes, que poden identificar els tickets d'implementació i de prova afectats per la decisió. Tractar-los com a referències registrades; utilitzeu el procés d'enllaç normal de Jira per separat quan necessiteu una relació de problemes.

Reviseu l'entrada completada amb les persones implicades. Comproveu que l'opció seleccionada i l'explicació escrita coincideixen. Confirmeu l'estat de desat abans de demanar als companys que confiïn en la versió més recent, sobretot si l'eina indica un estat local o fora de línia.

Utilitzeu l'estat per aclarir la posició actual

Power Pack proporciona estats proposat, acceptat, rebutjat i substituït. Acordeu com els utilitzarà el vostre equip perquè el lector pugui distingir una idea que espera una decisió d'una elecció que ja guia el lliurament.

Quan Maya, el responsable del producte, pren la decisió de notificació, l'equip registra la data i marca l'entrada Acceptada. Aquest estat descriu la posició de la decisió. No prova que la implementació s'hagi completat, que les proves hagin superat o que el llançament estigui autoritzat.

La mateixa distinció val per a Rebutjats. Si no s'adopta una proposta, una breu explicació pot evitar que la següent persona repeteixi una investigació sense saber que ja ha passat. Preserveu el raonament útil fins i tot quan no hi ha cap tiquet de lliurament.

Revisar una decisió quan canvien els seus supòsits

Després del llançament, imagineu que el portal s'amplia per incloure clients amb moltes sol·licituds actives. Informes d'assistència que alguns reben diversos correus electrònics habituals cada dia. Aquest és un nou context, directament relacionat amb la suposició original sobre el baix volum de missatges.

L'equip obre l'antic disc abans de proposar un canvi. Ara pot separar una compensació raonable anterior de la pregunta que té el producte avui. La decisió existent explica per què es va triar el correu electrònic immediat; no prohibeix una millor aproximació en diferents condicions.

Creeu una nova entrada proposada per a una opció de resum diari. Power Pack admet la duplicació d'una entrada en un registre proposat, que pot proporcionar un punt de partida. Reviseu amb atenció tots els camps copiats: és possible que les suposicions, les dates i les conseqüències antigues ja no s'apliquin.

Quan s'accepta la nova opció, marqueu el registre anterior Substituït i feu referència a la decisió de substitució al camp de substitució. Mantingueu llegible el raonament original en lloc de reescriure-lo com si l'equip sempre hagués volgut fer un resum.

Aquesta és una pràctica de documentació en equip. Els registres segueixen sent editables, així que accepteu crear entrades de substitució per a canvis substantius i reserveu les edicions ordinàries per a correccions o aclariments. No tracteu el registre com una pista d'auditoria immutable.

Feu que el registre sigui útil durant el treball diari

Utilitza el registre quan algú s'uneix a l'equip, proposa un redisseny o pregunta per què un tiquet inclou un requisit inusual. La cerca i el filtratge poden ajudar a localitzar una entrada al registre del tiquet. Power Pack també pot exportar Markdown d'estil ADR per a una revisió o un altre flux de treball de documentació.

Abans de compartir una exportació, comproveu que reflecteixi l'entrada actual i identifiqueu el problema on l'equip manté el registre. Un document descarregat és una instantània; futures edicions del tiquet no actualitzaran una còpia ja enviada a un altre lloc.

Comenceu amb una decisió que el vostre equip hagi pres recentment i és probable que la revisi. Escriu el context, les alternatives reals, l'enfocament escollit i les conseqüències. Col·loqueu aquest registre al costat del treball de Jira a Power Pack i, a continuació, demaneu a un company d'equip que s'hagi perdut la discussió que el llegeixi. Si poden explicar per què l'elecció té sentit i què justificaria canviar-la, el registre està fent un treball útil.

• Michael Nygard: Documentació de decisions d'arquitectura