Blog
“Questa risposta API non sembra diversa dal design su Figma?”
È venerdì, poco prima del rilascio. Un singolo messaggio su Slack blocca l’intero team.
Il PM aveva aggiornato diligentemente i ticket su Jira. Il designer aveva rifinito i file su Figma. Gli ingegneri avevano spedito PR a pieno ritmo. Tutti stavano facendo il loro miglior lavoro nel proprio ambito — eppure, nel momento in cui tutto si è incastrato, il disallineamento era innegabile.
Quello che segue è prevedibile: archeologia su Slack il venerdì sera. “Dove è stata decisa questa spec?” “Questa API non corrisponde al ticket originale — chi l’ha modificata?” Nessuno ha la risposta, perché il contesto dietro la decisione non è mai stato registrato da nessuna parte.
Siamo caduti in questo inferno del “non è colpa di nessuno, ma è tutto in fiamme” più volte di quanto vorremmo ammettere. Beaket è nato da quell’esperienza.
Le Spec sono progettate per mentire
Non è che le spec siano cattive. È che la struttura attorno a esse è rotta.
Le informazioni vivono naturalmente in posti diversi — i PM vivono in Jira, i designer in Figma, gli ingegneri in GitHub. Va bene così. Ogni strumento eccelle in ciò che fa, e non dovreste combatterlo.
Il problema è l’atto di copiare tutto in un’unica “fonte di verità”.
Nel momento in cui trascrivete qualcosa in Notion o in un wiki, esistono due copie. Quando una viene aggiornata, l’altra diventa una bugia. Una spec che smette di essere mantenuta perde il ragionamento dietro le decisioni passate e diventa un reperto che si allontana sempre di più dall’implementazione reale.
Non è un problema di disciplina. È un problema strutturale. Finché esistono copie, la divergenza è inevitabile.
Collegare, non copiare
Così abbiamo abbandonato l’approccio del “centralizzare tutto”. Costruire l’ennesimo wiki avrebbe portato allo stesso risultato.
Quello che Beaket fa invece è tracciare relazioni tra le informazioni che già esistono.
Non copiate i vostri design Figma o le discussioni GitHub in Beaket. Ogni strumento resta la fonte di verità per il proprio dominio. Beaket semplicemente collega quelle fonti attraverso il contesto del perché una decisione è stata presa.
Nello specifico, struttura le decisioni di progetto attorno a tre tipi di nodi:
- Spec — Il requisito di business. Cosa stiamo costruendo, e perché?
- Brief — Il registro delle decisioni di design. Cosa è stato deciso dal punto di vista del design, perché, e cosa si rompe senza.
- ADR — Il registro delle decisioni tecniche. Perché questo approccio? Quali alternative sono state considerate e scartate?
Questi tre si connettono tra loro attraverso archi, formando un grafo decisionale. Non scrivete specifiche dettagliate in Beaket. Catturate cosa è stato deciso, perché e a cosa si collega — niente di più.
La regola del “Scrivi meno”
Onestamente, questo è stato l’aspetto più dibattuto del prodotto.
“Non dovremmo permettere alle persone di scrivere più dettagli?” Certo che è venuto fuori. Ma nel momento in cui permetti la scrittura dettagliata, hai costruito un altro wiki. E i wiki marciscono sempre.
Così abbiamo intenzionalmente incorporato un vincolo in Beaket: scrivi meno.
L’euristica è semplice — il tuo io futuro verrebbe a cercare il ragionamento tra sei mesi? Se sì, scrivilo. Se no, non farlo. Le liste di parametri e i passaggi di implementazione appartengono a GitHub. Beaket contiene solo l’unità minima del perché.
Questo è un compromesso deliberato. Beaket non sarà mai uno strumento completo per la documentazione di design. È una scelta progettuale.
Il Ready Flag: una stretta di mano, non un’approvazione
C’è un altro meccanismo che siamo contenti di aver costruito.
Dopo che una Spec viene scritta, sia il designer che l’ingegnere impostano indipendentemente un flag “Ready”. Il designer segnala “ho compreso i requisiti dal punto di vista della UI”. L’ingegnere segnala “li ho compresi dal punto di vista tecnico”. Solo quando entrambi i flag sono impostati la Spec diventa “Ready”.
Non è un flusso di approvazione. È una stretta di mano.
Non “l’ho letto”, ma “dal mio punto di vista, siamo pronti a procedere”. È una salvaguardia strutturale contro l’inizio dell’implementazione su requisiti ambigui.
E se una Spec cambia dopo essere stata contrassegnata come Ready, il raggio d’impatto — ogni Brief e ADR collegato — viene automaticamente evidenziato. Niente più scavi nella cronologia di Slack.
Seguire la traccia delle decisioni
Beaket traccia la cronologia delle modifiche oltre il semplice chi ha cambiato cosa, quando. Cattura anche il perché.
Selezionate qualsiasi porzione di testo e potete risalire a quando è stata modificata, da chi e per quale motivo. Lo chiamiamo Decision Trail.
Non è una funzionalità appariscente. Ma tra sei mesi, quando qualcuno chiederà “perché questa spec è fatta così?” — la risposta è lì. Questo da solo cambia la velocità con cui un team può prendere decisioni.
Cosa non sappiamo ancora
Non pensiamo che Beaket sia adatto a ogni team.
Per un piccolo team che siede nella stessa stanza, dove il contesto è condiviso naturalmente, potrebbe essere eccessivo. Per organizzazioni con centinaia di persone, non abbiamo ancora validato a sufficienza.
Di una cosa siamo certi: perdere il contesto dietro le decisioni ha sempre un costo. E quel costo cresce esponenzialmente man mano che i team crescono e il tempo passa.
Beaket è uno strumento per tenere quel costo sotto controllo — strutturalmente. Non è una bacchetta magica. È più simile a un’assicurazione.
Se il vostro team si è mai trovato in una situazione in cui nessuno riesce a spiegare perché una decisione di design è stata presa — iniziate collegando anche solo una decisione. Vedete dove vi porta.