Idea principale

Dire che il codice è la fonte di verità del prodotto viene inteso spontaneamente come «la documentazione non serve più». L'opposizione è mal posta: non passa tra il codice e i documenti, ma tra due funzioni che i documenti svolgono e che non si distinguono.

Un artefatto che descrive dice che cosa fa il prodotto: una pagina di supporto su una funzionalità, un changelog, una specifica funzionale dello stato attuale, una documentazione commerciale su ciò che è possibile. Tutto questo si deduce dal repository, quindi è rigenerabile, quindi non ha senso mantenerlo.

Un artefatto che spiega dice perché: le discussioni e i ragionamenti che hanno portato a una scelta, la decisione di prodotto e le alternative scartate, il motivo per cui una decisione ne sostituisce un'altra. Niente di questo sta nel codice, e niente lo ritroverà. A ciò si aggiunge quello che non si deduce da alcun repository perché viene da fuori: un impegno contrattuale, un vincolo normativo, un documento esterno.

Il criterio di smistamento non è quindi la forma dell'artefatto né il suo autore, ma la domanda a cui risponde. Uno stesso documento può del resto rientrare in entrambi i casi, e allora va tagliato invece che classificato.

Il taglio si pratica fin dentro una scheda. In una scheda di oggetto del prodotto, il corpo descrive la realtà così com'è nel codice e si rigenera; il blocco degli scostamenti contiene il giudizio — ciò che diverge da ciò che si vorrebbe — e si mantiene. La regola che li tiene separati è assoluta e si dice in una frase: uno scostamento non modifica mai il corpo della scheda. Senza questo confine scritto, la prima rigenerazione si porta via la parte che è costata cara produrre, perché è l'unica che non si ritrova da nessuna parte.

Contributo di «Ho scritto l'ontologia di un prodotto. Tre volte ho creduto di aver finito.» (2026-08-11).

Perché è importante

È ciò che rende praticabile lo spostamento verso il codice senza distruggere niente. Senza questa linea si sceglie tra tenere tutto — e pagare la divergenza — e buttare tutto — e perdere il perché, la cui mancanza si vede solo quando qualcuno riapre una decisione.

Offre anche un test da applicare a qualsiasi documento di prodotto prima di deciderne la sorte: contiene una frase che nessuna lettura del repository permetterebbe di scrivere?

Sfumature e limiti

Il taglio è più netto in teoria che alla lettura di un documento reale: una specifica mescola di continuo il comportamento atteso e il motivo per cui è stato scelto, spesso nella stessa frase.

E ciò che spiega non è immune dall'invecchiamento. Un ragionamento conservato resta legato al contesto del suo tempo; non diverge dal prodotto come una descrizione, diventa semplicemente meno pertinente senza che niente lo segnali.

Domande aperte

• Che cosa, in un'organizzazione, cattura le spiegazioni nel momento in cui nascono, visto che si dicono in riunione e nelle revisioni del codice più che scriversi?