Rilascio canario del servizio Checkout

1) Perché è necessaria la documentazione delle operazioni

• trasforma la conoscenza orale in procedure ripetute;
• Specifica i limiti di responsabilità e i punti di escalation.
• è fonte di prove per la compliance e la sicurezza;
• accelera l'onboarding e riduce i rischi delle gole strette.

2) Tassonomia dei documenti (a cosa serve)

Policy - Intenzioni e cornici («cosa e perché»). Esempio: Politica di gestione degli incidenti.
Standard - Requisiti minimi obbligatori («quanto»). Esempio: tempi di aggiornamento dei certificati TLS.
Procedure operative standard: passaggi sequenziali («come»). Esempio: rilascio con scarico canaresco.
Runbook - Istruzioni passo passo per gli eventi tipici (alert/operazioni). Esempio: «API 5xx è cresciuta - algoritmo di azione».
Playbook è una serie di soluzioni di script con varianti e bivio. Esempio: «Problemi con il provider di pagamenti».
KB - Risposte, FAQ, informazioni sugli strumenti.
Checklist è un elenco breve delle voci obbligatorie prima delle azioni.
Record/Evidence - Cronologia passi completati, screenshot/logi/firme.

3) Principi di buona documentazione

Un'unica fonte di verità (SSOT). I documenti non vengono duplicati. spruzzare significa essere obsoleti.
Docs-as-Code. Memorizzate in Git, passate code-review, versioni e diffusioni - visibili.
Actionable-first. All'inizio c'è una breve scheda: quando eseguire, chi possiede, cosa fare, i criteri di completamento.
Atomatologia e direzionalità. Un solo documento è un task/workflow.
Aggiornabilità. Proprietario chiaro e aggiornamenti SLA (ad esempio trimestrali).
Osservabilità. I collegamenti a dashboard/alert/metriche sono incorporati.
Protezione-by-design. Classificazione della sensibilità, occultamento dei segreti, controllo dell'accesso.

4) Ciclo di vita documento (Governance)

1. Avvio: richiesta/ticket per il tipo di documento del proprietario.
2. Bozza: modello, minimo esempi, collegamenti agli standard e SLO.
3. Ruota: tecnica (SRE/piattaforma/sicurezza), procedurale (workflow manager).
4. Pubblicazione: nel ramo principale, contrassegna la versione/data, imposta lo stato (active/experimental/deprecated).
5. Formazione/Comunicazione: annuncio dei cambiamenti, breve training/demo.
6. Retrospettiva: a seguito di incidenti/esercitazioni apportare modifiche.
7. Controllo e archivio: traccia invariata (chi/quando ha cambiato), versioni obsolete nell'archivio.

5) Struttura SOP/Runbook (minimo)

1. Scheda: Nome, ID, Versione/Data, Proprietario, Ruoli di responsabilità, Criteri/standard associati.
2. Quando applicare: condizioni di avvio (alert/evento/finestra di lavoro).
3. Preparazione: diritti/strumenti/dati, rischio-valutazione, comunicazioni.
4. Passaggi numerati, con comandi/screenshot/risultati previsti.
5. I criteri SLI/SLO sono chiari.
6. Escalation: chi, quando e come (canale, telefono, provider).
7. Sicurezza/compilazione: dati sensibili, divieti, registrazioni di azioni.
8. Post-action: chiusura dei tesserati, aggiornamento dello stato, raccolta delle prove.
9. Cronologia modifiche (changelog).

6) Stile e regole di disegno

Chiaro e breve: 1 passo - 1 azione - 1 risultato.
Imperativo: «Esegui»..., «Controlla»..., «Ritira»...
Screenshot/comandi - accanto al passo; comandi - Blocchi copiati Nota l'output previsto.
Variabilità: rami «Se A il passo X, se B il passo Y».
Coerenza: dove è appropriato - specificare le regioni/provider/tenenti.
Localizzazione: documenti chiave - minimo in 2 lingue; Specificare lo stato delle traduzioni.
Tag e ricerca: servizio, componente, provider, tipo di incidente, SLO, versione.

7) Docs-as-Code e strumenti

Magazzino: Git (main/feat/bugfix), rivisitazione, richired checks.
Formato: Markdown/AsciiDoc; diagrammi nel PlantUML/Mermaid; schemi JSON/YAML.
Pubblicazione sito statico (Docusaurus/MkDocs) + ricerca.
Verifica: lente CI, test dei riferimenti, ortografia, validatori dei blocchi di codice.
Integrazioni: ChatOps comandi '/runbook open X ', visualizza l'ultima versione in alert.
Connessioni: CMDB/directory dei servizi, documentazione del servizio.

8) Controllo e classificazione degli accessi

Классы: Public / Internal / Confidential / Restricted.
Separazione: istruzioni pubbliche (stati comuni) vs chiuse (chiavi, comandi, diagrammi di rete).
I segreti sono proibiti nel testo; usare il segreto-magazzino e i playsholder.
Controllo - Registro di lettura/modifica per le SOP sensibili.

9) Relazione con incidenti e comunicati

Ogni alert fa riferimento a runbook rilevanti.
In ogni incidente c'è un riferimento alla SOP usata e all'assegno di contrassegno.
Dopo RCA, aggiorna i documenti come un'azione CAPA.
Prima del rilascio, checklist: cancellazione pronta, bandiere di degrado, contatti dei provider.

10) Set minimo obbligatorio (MVP-dock-pack)

Politica di gestione degli incidenti e escalation (SEV/P livelli, timing).
Standard di monitoraggio e alert policy (burn rate, quorum).
SOP: rilascio/reimpostazione (canary/blue-green), migrazioni di database (expand/contract).
Runbook: «Alto errore-rate», «Crescita p99», «Calo del successo dei pagamenti», «Problema TLS/DNS».
Playbook dei provider esterni (pagamenti/KYC/CDN): contatti, limiti, folback.
Criteri di gestione dei segreti e della disponibilità.
Modelli RCA e Post-mortem.
Tabella dei proprietari di servizi (RACI) e mappa dei dashboard.

11) Metriche di qualità documentazione (SLO documento)

Coverage:% percorsi critici con SOP/Runbook.
Freshness - Percentuale di documenti più recenti di N giorni (ad esempio 90).
Usability:% degli incidenti chiusi secondo runbook senza escalation.
Findability - Tempo medio per la ricerca del documento desiderato (in base a sondaggi/login).
Defect rate: numero di commenti su/100 documenti.
Adoption: percentuale di alert con riferimento corretto al runbook.
Compliance evidence rate:% delle attività con prove applicate.

12) Assegno fogli

Foglio di assegno per la creazione di SOP

• Il proprietario e il target sono stati definiti.
• Ci sono condizioni di avvio e criteri di stop.
• I passaggi sono riprodotti, verificati da un altro ingegnere.
• Sono stati incorporati collegamenti a dashboard/alert/strumenti.
• Senza segreti; ci sono playsholder e un riferimento al vault.
• È stato descritto il ritorno e l'escalation.
• È stato aggiunto un assegno-foglio «dopo le azioni».
• Versione, data, changelog.

Foglio di assegno con gelosia

• Il documento corrisponde a una tassonomia (non mescola criteri e passi).
• Linguaggio semplice, imperativo, senza ambiguità.
• I comandi sono stati controllati in «secco «/stage.
• I rischi e i punti di controllo sono specificati.
• La disponibilità è corretta.
• Linter/validatori superati in CI.

13) Localizzazione, versione e disponibilità

Versione: "MAJOR. MINOR. PATCH'in cui MAJOR rompe la compatibilità dei processi.
Lingue - Segnare la lingua di origine e lo stato delle traduzioni (up-to-date/needs review).
Fattore di forma: visualizzazione mobile/notturna per on-call, schede di stampa IC.

14) Automazione doc (da pratica)

Genera wireframe SOP da modelli CLI ('doc new sop --service = payments').
Inserisce automaticamente i collegamenti agli ultimi dashboard sui tag del servizio.
Promemoria documenti scaduti (freshness SLA).
Esporta il pacchetto Evidence durante il periodo (PDF/ZIP) per il controllo.
Collegare i ticetti degli incidenti alla versione dei documenti utilizzati per la soluzione.

15) Sicurezza e compliance

Le sezioni «Rischi» e «Attività di controllo» sono obbligatorie.
Memorizzazione dell'evidence in un archivio immutabile con firme/hash.
Allineamento alle normative (ad esempio, data di notifica/retensione), proprietario espliciti della conformità.

16) Anti-pattern

Wiki labirinto senza proprietari o date di aggiornamento.
I politici mescolati ai comandi non troveranno nulla da fare.
Documenti senza contesto (nessun SLO, nessun dashboard, nessuna escalation).
Screenshot con segreti o istruzioni per cliccare qui senza alternative CLI.
«Un guru sa come» - tribal knowledge senza fissazione.
I PDF archiviati come unica versione non sono modificabili o ricercati.

17) Modelli (sezioni)

Cappello SOP (esempio)

SOP-ID: OPS-REL-001

18) Incorporazione giornaliera

Tazze doc settimanali: analisi di 1-2 documenti, aggiornamento, condivisione delle esperienze.
Game-days - Verifica la realtà di SOP/Runbook nelle simulazioni.
Onboarding: percorso del principiante attraverso una serie di documenti obbligatori + quiz brevi.
Doc-debito: backlog di miglioramento con priorità.

19) Totale

La documentazione delle operazioni non è un archivio, ma uno strumento di lavoro. Quando viene gestito come codice, possiede proprietari, metriche di freschezza e integrato in incidenti, release e formazione, l'organizzazione diventa prevedibile: meno errori, più rapidità di reazione, comprensibile responsabilità e pronto per l'ispezione. Scrivere brevemente, aggiornare regolarmente, automatizzare la routine e la documentazione inizia a risparmiare tempo e denaro.