Sortie Canaries du service Checkout

1) Pourquoi la documentation des opérations est nécessaire

• transforme la connaissance orale en procédures reproductibles ;
• définit les limites de responsabilité et les points d'escalade ;
• sert de source de preuves pour la conformité et la sécurité ;
• accélère l'engorgement et réduit les risques de « gorges étroites ».

2) Taxonomie des documents (quoi)

Politique : intentions et cadre (« quoi et pourquoi »). Exemple : Politique de gestion des incidents.
Standard (Standard) : exigences minimales obligatoires (« combien »). Exemple : date limite de mise à jour des certificats TLS.
SOP/Procedure (Procédure d'exploitation standard) : étapes successives (« comment »). Exemple : Sortie d'une version canarienne.
Runbook : instructions étape par étape pour les événements types (alertes/opérations). Exemple : « L'API 5xx a grandi - algorithme d'action ».
Playbook : un ensemble de solutions de scénarios avec des options et des fourchettes. Exemple : « Problèmes avec le fournisseur de paiement ».
KB (Base de connaissances) : réponses, FAQ, aide sur les outils.
Checklist : brève liste des points obligatoires avant les actions.
Record/Evidence : journal des étapes exécutées, captures d'écran/logs/signatures.

3) Principes d'une bonne documentation

Source unique de vérité (SSOT). Les documents ne sont pas dupliqués ; pulvériser, c'est être obsolète.
Docs-as-Code. Nous le stockons dans Git, passons par le code-review, les versions et les diffas sont visibles.
Actionable-first. Au début, une brève carte : quand lancer, qui est le propriétaire, quoi faire, critères d'achèvement.
Atomicité et adressabilité. Un document est une tâche/un processus.
Mise à jour. Un propriétaire clair et une mise à jour SLA (par exemple, trimestrielle).
L'observabilité. Les références aux dashboards/alerts/métriques sont intégrées.
Security-by-design. Classification des sensibilités, masquage des secrets, contrôle d'accès.

4) Cycle de vie du document (Gouvernance)

1. Initiation : demande/ticket → type de document → propriétaire.
2. Brouillon : modèle, minimum d'exemples, références aux normes et aux SLO.
3. Revew : technique (SRE/plateforme/sécurité), procédural (gestionnaire de processus).
4. Publication : dans la branche principale, marque la version/date, attribution du statut (active/experimental/deprecated).
5. Formation/Communication : annonce de changement, courte formation/démo.
6. Rétrospective : À la suite des incidents/exercices, apporter des modifications.
7. Audit et archives : piste immuable (qui/quand a changé), versions obsolètes dans l'archive.

5) Structure SOP/Runbook (minimum)

1. Carte : Titre, ID, Version/Date, Propriétaire, Rôles responsables, Politiques et normes connexes.
2. Quand appliquer : les conditions de démarrage (alerte/événement/fenêtre de travail).
3. Préparation : droits/outils/données, évaluation des risques, communications.
4. Étapes : numérotées, avec commandes/captures d'écran/résultats attendus.
5. Critères de succès/de recul : Seuils SLI/SLO clairs.
6. Escalade : qui, quand et comment (canal, téléphone, fournisseur).
7. Sécurité/conformité : données sensibles, interdictions, enregistrements d'actions.
8. Post-actions : fermeture des tiquets, mise à jour du statut, collecte des preuves.
9. Historique des changements (changelog).

6) Style et règles de décoration

Clair et court : 1 étape - 1 action - 1 résultat.
L'impératif : « Accomplir »..., « Vérifier »..., « Reculer »....
Captures d'écran/commandes : à côté de l'étape ; commandes - blocs à copier ; Acceptez la conclusion attendue.
Variabilité : branches « Si A → l'étape X si B → l'étape Y ».
Cohorte : où pertinent - indiquer les régions/fournisseurs/tenants.
Localisation : documents clés - au moins 2 langues ; indiquez le statut des traductions.
Balises et recherche : service, composant, fournisseur, type d'incident, SLO, version.

7) Docs-as-Code et outils

Stockage : Git (main/feat/bugfix), PR-revew, required checks.
Format : Markdown/AsciiDoc ; Diagrammes dans PlantUML/Mermaid ; circuits JSON/YAML.
Publication : site statique (Docusaurus/MkDocs) + recherche.
Vérification : CI-lint, test de référence, orthographe, validateurs de blocs de code.
Intégrations : ChatOps commandes '/runbook open X ', affiche la dernière version en alertes.
Communications : CMDB/annuaire de services ↔ documentation ↔ dashboards.

8) Contrôle d'accès et classification

Классы: Public / Internal / Confidential / Restricted.
Division : instructions publiques (états généraux) vs privées (clés, commandes, diagrammes de réseau).
Secrets : interdits dans le texte ; utiliser le coffre-fort secret et les placcholders.
Audit : journal de lecture/changement pour les SOP sensibles.

9) Communication avec les incidents et les communiqués

Dans chaque alerte, une référence au runbook pertinent.
Dans chaque incident, une référence au SOP utilisé et un chèque de marque.
Après RCA - mettre à jour les documents en tant qu'action CAPA.
Avant la sortie - checklist : prêt à revenir en arrière, drapeaux de dégradation, contacts des fournisseurs.

10) Ensemble minimum obligatoire (pack MVP-Dock)

Politique de gestion des incidents et escalade (niveaux SEV/P, temps).
Norme de surveillance et politique d'alerte (taux de burn, quorum).
SOP : sortie/retour (canary/blue-green), migration OBD (expand/contract).
Runbook : « Taux d'erreur élevé », « Croissance p99 », « Baisse du succès des paiements », « Problème TLS/DNS ».
Playbook des fournisseurs externes (paiements/KYC/CDN) : contacts, limites, folbacks.
Politique de gestion des secrets et des accès.
Modèles RCA et Post-mortem.
Tableau des propriétaires de services (RACI) et carte dashboard.

11) Métriques de qualité de la documentation (document SLO)

Coverage :% des chemins critiques avec SOP/Runbook.
Freshness : proportion de documents frais N jours (p. ex. 90).
Usability :% d'incidents fermés selon le runbook sans escalade.
Findability : médiane du temps de recherche du document souhaité (par sondages/logs).
Defect rate : nombre de remarques par rhubarbe/100 documents.
Adoption : proportion d'alerts avec une référence correcte au runbook.
Taux de conformité :% des tâches avec preuves jointes.

12) Chèques-feuilles

Chèque de création de SOP

• Le propriétaire et le public cible ont été identifiés.
• Il y a des conditions de démarrage et des critères d'arrêt.
• Les étapes sont reproductibles, validées par un autre ingénieur.
• Les références aux dashboards/alertes/outils sont intégrées.
• Pas de secrets ; il y a des placcholders et une référence au vault.
• Le recul et l'escalade sont décrits.
• Une chèque « après action » a été ajoutée.
• Version, date, changelog.

Check-list je revois

• Le document est conforme à la taxonomie (ne mélange pas les politiques et les étapes).
• Le langage est simple, impératif, sans ambiguïté.
• Les commandes sont vérifiées en « course à sec « /steadge.
• Les risques et les points de contrôle sont indiqués.
• L'accessibilité (Internal/Restricted) est correcte.
• Les linters/validateurs en CI sont passés.

13) Localisation, version et disponibilité

Version : 'MAJOR. MINOR. PATCH ', où MAJOR brise la compatibilité des processus.
Langues : notez la langue « source » et le statut des traductions (up-to-date/needs review).
Facteur de forme : affichage mobile/nocturne pour l'appel, cartes imprimées IC.

14) L'automatisation du quai (de la pratique)

Génération de squelettes SOP à partir de modèles CLI ('doc new sop --service = payments').
Insertion automatique de liens vers les derniers dashboards par tags de service.
Bots de rappel de documents périmés (SLA freshness).
Exportation du paquet Evidence par période (PDF/ZIP) pour audit.
Lier les tickets d'incident à la version des documents utilisés dans la solution.

15) Sécurité et conformité

Sections obligatoires « Risques » et « Activités de contrôle ».
Stockez evidence dans une archive immuable avec des signatures/hachages.
Ancrage à la réglementation (par exemple, délais de notification/rétractation), propriétaires de conformité explicites.

16) Anti-modèles

« Vicky labyrinthe » sans les propriétaires et les dates de mise à jour.
Les politiciens mélangés aux équipes - personne ne trouvera quoi faire.
Documents sans contexte (pas de SLO, dashboards, escalades).
Captures d'écran avec des secrets ou des instructions « cliquez ici » sans alternatives CLI.
« Un gourou sait comment » est une connaissance tribale sans fixation.
Les PDF archivés en tant que version unique ne sont pas édités, recherchés.

17) Modèles (fragments)

Chapeau SOP (exemple)

SOP-ID: OPS-REL-001

18) Intégrer dans le travail quotidien

Cercles de doc hebdomadaires : examen 1-2 documents, actualisation, échange d'expériences.
Jeux-jours : vérification de la réalité de SOP/Runbook en simulations.
Onbording : itinéraire de débutant à travers un ensemble de documents obligatoires + courts quiz.
Devoir de quai : backlog des améliorations avec priorité (impact × effet).

19) Résultat

La documentation des opérations n'est pas une archive, mais un outil de travail. Lorsqu'il est exécuté comme un code, qu'il a des propriétaires, des mesures de fraîcheur et qu'il est intégré dans les incidents, les communiqués et la formation, l'organisation devient prévisible : moins d'erreurs, réaction plus rapide, responsabilité compréhensible et préparation à la vérification. Écrivez court, mettez à jour régulièrement, automatisez votre routine - et la documentation commencera à économiser du temps et de l'argent.