Documentare il codice per il te del futuro:ROI 18x

Quando costruisci da solo, documentare il codice non serve agli altri: serve al te del futuro, che ha dimenticato tutto. Dieci minuti di appunti, quando ho costruito una funzionalità, mi avrebbero fatto risparmiare le tre ore che ho poi passato a fare reverse engineering del mio stesso database. Un ritorno di 18 volte, su una sola funzionalità.

La documentazione sembra l'abitudine più aziendale e più saltabile che un solopreneur possa adottare. È il contrario: è l'abitudine che permette a un'azienda di una sola persona di comportarsi come un team — perché chi ha scritto il codice sei mesi fa è, di fatto, un'altra persona.

Il giorno in cui ho dimenticato lo schema del mio database

Tre mesi prima avevo costruito una funzionalità complessa per la piattaforma del mio acceleratore. Un database multi-tabella, strutturato con cura, policy di sicurezza, tutto. Ci erano volute sei ore per progettarla e implementarla, ed ero fiero del risultato.

Poi mi è servito aggiungere un solo campo a quella funzionalità. Ho aperto il codice, guardato le tabelle, iniziato a leggere — e non avevo assolutamente idea del perché avessi preso certe decisioni. Perché quattro tabelle di giunzione invece di due? Perché questa colonna è opzionale? Perché questa regola di accesso controlla due cose invece di una?

Ho passato tre ore a fare reverse engineering del mio codice. Non di quello di qualcun altro. Del mio. Nessun appunto sulla funzionalità, nessuna spiegazione del design, nulla che mostrasse come i pezzi si collegassero. Solo codice, e una memoria che aveva cancellato tutto in silenzio.

In un team le decisioni vengono discusse e la conoscenza condivisa. Da solo c'è un'unica copia del "perché" — nella tua testa — e scade più in fretta di quanto pensi. È il costo nascosto dello sviluppo in solitaria, e quasi nessuno lo mette in conto.

Documentare il codice: i conti del punto di pareggio

Dieci minuti di documentazione, quando ho costruito quella funzionalità, mi avrebbero fatto risparmiare tre ore dopo. ROI di 18 volte, su una funzionalità. Ora scala il discorso: ho 45 funzionalità in produzione. Se documentare in anticipo fa risparmiare circa due ore per funzionalità nel tempo, sono 90 ore all'anno — 7.200 € del mio tempo a 80 €/ora, comprati con dieci minuti per funzionalità.

I conti sull'intero ciclo di vita sono ancora più sproporzionati. Prendi una funzionalità e dieci modifiche future:

Circa 18 ore risparmiate per funzionalità nell'arco della sua vita. Su 45 funzionalità sono 815 ore — 65.200 € di valore a 80 €/ora. Ma, onestamente, i soldi non sono il punto. Il punto è ciò che la documentazione ti permette di fare: rifattorizzare senza paura perché sai cosa si romperà, costruire sul lavoro passato perché ricordi i tuoi stessi progetti e fare debug in pochi minuti perché le trappole sono messe per iscritto.

Il libroThe Solopreneur RevolutionLuis Gonçalves su come costruire un'attività da solopreneur con l'IA mentre sei ancora dipendente.Scopri il libro →

I quattro documenti di cui ogni funzionalità ha bisogno

Dopo 45 funzionalità ho scelto quattro tipi di documenti, in ordine di importanza.

Documento del perché — il contesto di business. Il più importante e il più saltato. Quale problema risolve questa funzionalità, che impatto ha e perché hai fatto le scelte di design chiave? È il documento che impedisce al te del futuro di "ottimizzare" via una decisione che esisteva per un motivo. Come architetto del tuo prodotto, le tue decisioni sono l'unico asset che non si può rigenerare — scrivile.

Documento del cosa — come funziona. Le tabelle coinvolte, come i dati attraversano la funzionalità, cosa accade e in quale ordine. È il documento che risponde a "perché quattro tabelle di giunzione?" in trenta secondi invece che in tre ore.

Documento del come — la guida all'uso. Come tu (o un giorno una persona del supporto) fai funzionare davvero la funzionalità: dove si configura, cosa vedono gli utenti, quali sono i passaggi.

Documento delle trappole — gli appunti di troubleshooting. Ogni trappola in cui sei caduto: l'impostazione che sembra rotta ma è solo lenta, i dati che devono esistere prima che qualcosa funzioni, la soluzione all'errore che rivedrai di sicuro. Ogni voce fa risparmiare una futura sessione di debug.

Rendere automatica la documentazione

Ecco l'obiezione onesta: non voglio spendere nemmeno dieci minuti per funzionalità a scrivere documentazione a mano. È noioso, ed è tempo sottratto alla costruzione. Prima dell'AI quell'obiezione vinceva — la documentazione richiedeva da due a tre ore per funzionalità, quindi la saltavo.

Con l'AI l'attrito è sparito. Ogni funzionalità che costruisco parte da un brief strutturato — un PRP — che contiene già l'obiettivo, le decisioni di design e le trappole. Quando la funzionalità va in produzione, l'AI trasforma quel brief in documentazione in circa dieci minuti. Completa, coerente, e non salta mai sezioni per noia.

Poi una regola tiene viva l'abitudine: se rilascio codice senza documentazione, non ho rilasciato. La mia checklist la impone — funzionalità, test, documentazione: tutte e tre o non viene integrata. Non posso aggirare la mia stessa regola, ed è esattamente questo il punto.

Il risultato: oltre mille pagine di documentazione ricercabile, scritta in gran parte dall'AI, che copre ogni funzionalità del prodotto. Zero momenti da "ma a cosa pensavo?" da allora. E quando assumerò il mio primo ingegnere, erediterà tutto dal primo giorno — due settimane di vantaggio nell'onboarding che la maggior parte delle aziende costruite da una sola persona semplicemente non ha.

12 settimaneLa carriera aziendale non è mai stata il pianoCandidati al Solopreneur Accelerator.Candidati ora →

Domande frequenti

Perché documentare un progetto su cui lavoro solo io?

Perché tra sei mesi sei, a tutti gli effetti pratici, un'altra persona. Ho passato tre ore a fare reverse engineering del mio database perché non avevo documentato nulla. La documentazione in solitaria non è burocrazia: è un messaggio dal te di oggi al te del futuro, e il te del futuro lo legge sempre con gratitudine.

Cosa devo documentare, esattamente?

Quattro cose per funzionalità: perché esiste e perché hai preso le decisioni chiave; cosa fa tecnicamente; come si usa; e le trappole in cui sei già caduto. Se ne scrivi una sola, scrivi il perché — è l'unica parte che il codice stesso non potrà mai dirti.

Quanto tempo richiede la documentazione con l'AI?

Circa dieci minuti per funzionalità. Se costruisci a partire da un brief strutturato, l'AI genera la documentazione da materiale già esistente: è una conversione, non un progetto di scrittura. Il costo di una volta era da due a tre ore per funzionalità, ed è per questo che nessuno lo faceva.

Qual è il ROI del documentare per un fondatore solitario?

I miei numeri: dieci minuti di documentazione contro tre ore per ricapire tutto fanno 18 volte su una singola modifica. Nell'arco della vita di una funzionalità sono circa 18 ore risparmiate; sulle mie 45 funzionalità, circa 815 ore — 65.200 € a 80 €/ora. Più la parte che non ha prezzo: la sicurezza di modificare il tuo stesso codice senza paura.