ADR 0001 - Docs as Code

Stato

Accettata.

Contesto

Playroll ha bisogno di una documentazione che possa crescere insieme alla codebase e supportare più tipi di pubblico:

• Gli sviluppatori hanno bisogno di contratti di architettura e di ciclo di vita.
• I tester hanno bisogno di flussi di risoluzione problemi.
• Gli operatori hanno bisogno di runbook di rilascio e monitoraggio.
• Gli investitori hanno bisogno di definizioni di KPI stabili e di una semantica di monitoraggio chiara.

I commenti estemporanei sui ticket non sono sufficienti, perché diventano difficili da cercare e divergono dall'implementazione.

Decisione

Mantenere la documentazione di Playroll come sito statico nel repository playroll-docs.

Usare pagine Markdown/MDX curate per architettura, runbook e decision record. Usare pagine di riferimento generate dove l'estrazione dalla source-of-truth è pratica, in particolare per gli eventi di telemetria e la documentazione dello schema del database.

Conseguenze

• Le modifiche alla documentazione possono essere revisionate come si fa con il codice.
• Il sito può essere distribuito come file statici.
• I link rotti possono essere verificati in CI.
• La conoscenza operativa ha una casa stabile al di fuori dei ticket Linear e della cronologia delle chat.
• Il team deve mantenere la documentazione aggiornata quando cambia il comportamento di ciclo di vita, telemetria, validazione, database o rilascio.