Eliberarea canarului serviciului Checkout

1) De ce am nevoie de documentația tranzacției?

• transformă cunoștințele orale în proceduri repetabile;
• Definește limitele responsabilității și punctele de escaladare
• servește drept sursă de dovezi pentru conformitate și siguranță;
• accelerează îmbarcarea și reduce riscurile de „gât îngust”.

2) Taxonomia documentelor (ce este ceea ce)

Politică: intenții și cadru („ce și de ce”). Exemplu: Politica de gestionare a incidentelor.
Standard: cerințe minime obligatorii („cât de mult”). Exemplu: date de reînnoire a certificatului TLS.
POS/Procedură: pași secvențiali („as”). Exemplu: Eliberați cu rola canar.
Runbook: instrucțiuni pas cu pas pentru evenimente tipice (alerte/operații). Exemplu: „API 5xx a crescut - algoritm de acțiuni”.
Playbook: un set de soluții de scenariu cu opțiuni și furci. Exemplu: „Probleme cu un furnizor de plăți”.
KB (Baza de cunoștințe): răspunsuri, întrebări frecvente, ajutor pentru instrumente.
Lista de verificare - o listă scurtă de elemente necesare înainte de acțiuni.
Înregistrare/Dovezi: jurnal de pași finalizate, capturi de ecran/busteni/semnături.

3) Principii de bună documentare

Sursa unică a adevărului (SSOT). Documentele nu sunt duplicate; pentru a pulveriza este de a deveni învechit.
Docs-as-Code. Stocăm în Git, trecem codul de revizuire, versiunile și difuzoarele sunt vizibile.
Actionable-în primul rând. La început - o carte scurtă: când să înceapă, cine este proprietarul, ce să facă, criterii de finalizare.
Atomicitate și adresabilitate. Un document - o sarcină/proces.
Actualizare. Ștergeți actualizările proprietarului și SLA (de ex. trimestrial).
Observabilitate. Link-urile către tablouri de bord/alerte/metrici sunt încorporate.
Securitate prin design. Clasificarea sensibilităţii, mascarea secretă, controlul accesului.

4) Ciclul de viață al documentelor (Guvernanță)

1. Inițiere: cerere/bilet → tip document → proprietar.
2. Proiect: șablon, exemple minime, trimiteri la standarde și SLO.
3. Revizuire: tehnică (SRE/platformă/siguranță), procedurală (manager de proces).
4. Publicație: în ramura master, marcarea versiunii/datei, atribuirea statutului (activ/experimental/depreciat).
5. Training/Comunicare: anunțarea schimbărilor, training scurt/demo.
6. Retrospectivă: pe baza rezultatelor incidentelor/exercițiilor, efectuați modificări.
7. Audit și arhivă: urme imuabile (cine/când a fost schimbat), versiuni învechite în arhivă.

5) Structura SOP/Runbook (minim)

1. Card: Nume, ID, Versiune/Data, Proprietar, Roluri responsabile, Politici/Standarde conexe.
2. Când se aplică: condiții de pornire (avertizare/eveniment/fereastră de lucru).
3. Pregătirea: drepturi/instrumente/date, evaluarea riscurilor, comunicări.
4. Pași: numerotate, cu comenzi/capturi de ecran/rezultate așteptate.
5. Criterii de succes/revenire: praguri SLI/SLO clare.
6. Escaladare: cine, când și cum (canal, telefon, furnizor).
7. Securitate/conformitate: date sensibile, interdicții, evidența acțiunilor.
8. Post-acțiuni: bilete de închidere, actualizarea stării, colectarea probelor.
9. Istoria schimbărilor (changelog).

6) Reguli de stil și design

Clar și scurt: 1 pas - 1 acțiune - 1 rezultat.
Imperativ: „Executați”..., „Verificați”..., „Roll back”....
Capturi de ecran/comenzi: lângă pas; comenzi - blocuri copiate; notați ieșirea așteptată.
Variabilitate: ramuri "Dacă A → pasul X, dacă B → pasul Y.
Cohortă: dacă este cazul - specificați regiunile/furnizorii/chiriașii.
Localizare: documente cheie - cel puțin 2 limbi; Specificați starea traducerilor.
Etichete și căutare: serviciu, componentă, furnizor, tip incident, SLO, versiune.

7) Docs-as-Code și instrumente

Stocare: Git (main/feat/bugfix), revizuire PR, verificări necesare.
Format: Markdown/AsciiDoc; Grafice în schemele PlantUML/Sirenă JSON/YAML.
Publicație: site static (Docusaurus/MkDocs) + căutare.
Verificare: CI-scame, link test, ortografie, cod bloc validatoare.
Integrări: comenzile ChatOps '/runbook open X ', afișând cea mai recentă versiune în alerte.
Link-uri: CMDB/catalog de servicii ↔ documentație ↔ tablouri de bord.

8) Controlul și clasificarea accesului

Классы: Public/Intern/Confidențial/Restricționat.
Separare: instrucțiuni publice (stări generale) vs private (chei, comenzi, diagrame de rețea).
Secretele: interzise în text; utilizați stocarea secretă și înlocuitorii.
Audit - Citiți/schimbați jurnalul pentru POS-uri sensibile.

9) Comunicarea cu incidente și eliberări

În fiecare alertă - un link către runbook-ul relevant.
În fiecare incident, o trimitere la POS utilizat și o verificare a marcajelor.
După RCA - actualizarea documentelor ca acțiune CAPA.
Înainte de lansare - lista de verificare: pregătirea rollback, steaguri de degradare, contacte furnizor.

10) Set minim necesar (MVP Dock Pack)

Gestionarea incidentelor și politica de escaladare (nivelurile SEV/P, calendare).
Monitorizarea politicii standard și de alertă (rata de ardere, cvorum).
SOP: release/rollback (canar/albastru-verde), migrații de baze de date (extindere/contract).
Runbook: „Rata de eroare ridicată”, „creșterea p99”, „Scăderea succesului de plată”, „Problema TLS/DNS”.
Playbook de furnizori externi (plăți/KYC/CDN): contacte, limite, folback-uri.
Politica de gestionare a secretului și a accesului.
Șabloane RCA și post-mortem.
Service Ownership Table (RACI) și harta tabloului de bord.

11) Măsurători ale calității documentației (Document SLO)

Acoperire:% din căile critice cu SOP/Runbook.
Prospețime: ponderea documentelor este mai recentă decât zilele N (de exemplu, 90).
Usability:% din incidente sunt închise în conformitate cu runbook fără escaladare.
Findability: timpul mediu de căutare pentru documentul dorit (prin sondaje/jurnale).
Rata de defect: numărul de comentarii per revizuire/100 documente.
Adopție: procent de alerte cu referință corectă la runbook.
Rata dovezilor de conformitate:% din sarcinile cu dovezi atașate.

12) Liste de verificare

Lista de verificare a creării POS

• Proprietarul și publicul țintă definit.
• Există condiții de pornire și criterii de oprire.
• Pașii sunt reproductibili, verificați de un alt inginer.
• Link-uri încorporate către tablouri de bord/alerte/instrumente.
• Fără secrete; există substituenți și o legătură de seif.
• Descrie rollback și escaladarea.
• Adăugat „după acțiune” listă de verificare.
• Versiune, dată, changelog.

Review lista de verificare

• Documentul corespunde taxonomiei (nu se amestecă politicile și pașii).

Limbajul este simplu, imperativ, fără ambiguitate.

• Echipe testate în „run uscat „/etapă.
• Riscurile și punctele de control sunt indicate.
• Intern/Restricționat este corect.
• Linters/validatori a trecut în CI.

13) Localizare, versiune și disponibilitate

Versiunea: 'MAJOR. MINOR. PATCH ', în cazul în care MAJOR rupe compatibilitatea procesului.
Limbi: Marcați limba „sursă” și starea traducerii (revizuire actualizată/necesară).
Factor de formă: display mobil/noapte pentru cartele IC tipărite.

14) Automatizarea docurilor (din practică)

Generarea de cadre SOP din template-uri CLI ('doc new sop --service = plăți').
Auto-insert link-uri la cele mai recente tablouri de bord de service tag-uri.
Documente restante memento bots (SLA prospețime).
Exportul pachetului Dovezi pentru perioada (PDF/ZIP) pentru audit.
Asociați biletele de incident cu versiunea documentelor utilizate în soluție.

15) Siguranță și conformitate

Secțiunile obligatorii „Riscuri” și „Măsuri de control”.
Stocarea dovezilor într-o arhivă neschimbată cu semnături/hash-uri.
Obligatoriu pentru reglementări (ex. perioade de notificare/păstrare), proprietari de conformitate explicită.

16) Anti-modele

„Wiki Maze” fără proprietari și date de actualizare.
Politicienii amestecați cu echipe - nimeni nu va găsi ce să facă.
Documente fără context (fără SLO, tablouri de bord, escaladări).
Capturi de ecran cu secrete sau instrucțiuni „click aici” fără alternative CLI.
„Un guru știe cum” - cunoștințe tribale fără fixare.
PDF-uri arhivate ca singura versiune nu sunt editate, nu căutate.

17) Șabloane (fragmente)

Capacul POS (exemplu)

SOP-ID: OPS-REL-001

18) Încorporarea în munca de zi cu zi

Doc-cercuri săptămânale: analiza 1-2 documente, actualizarea, schimbul de experiență.
Joc-zile: SOP/Runbook reality check în simulări.
Onboarding: traseul începătorului printr-un set de documente obligatorii + chestionare scurte.
Datoria de andocare: restanțe de îmbunătățiri cu prioritizare (impact × efort).

19) Linia de jos

Documentația tranzacției nu este o arhivă, ci un instrument de lucru. Când este gestionat ca cod, are proprietari, valori de prospețime și este încorporat în incidente, lansări și instruire, organizația devine previzibilă: mai puține greșeli, reacții mai rapide, responsabilitate ușor de înțeles și disponibilitate pentru audit. Scrieți pe scurt, actualizați în mod regulat, automatizați rutina - iar documentația va începe să economisească timp și bani.