KM et cycle de vie SI¶

La gestion des connaissances n'est pas un projet a côté — elle s'intégré dans les rituels quotidiens du système d'information.

La documentation vivante face à la documentation morte¶

La plupart des équipes ont de la documentation. Peu en ont de la documentation utile. La distinction fondamentale n'est pas la qualité initiale d'un document — c'est sa capacité a rester juste au fil du temps.

Une documentation morte est redige une fois, archivee, et jamais mise à jour. Elle devient inexacte en quelques semaines, ignore en quelques mois. L'équipe cesse de la consulter parce qu'elle sait qu'elle ne peut plus lui faire confiance. Ce phenomene crée une boucle autodestructrice : la documentation n'est plus mise à jour parce qu'elle est fausse, elle est fausse parce qu'elle n'est plus mise à jour.

Une documentation vivante est structurellement liee au code ou aux décisions qu'elle décrit. Sa mise à jour fait partie du workflow normal. Elle a un propriétaire clair. Elle est revisee régulièrement, avec un critère de révision défini.

Les principes de la documentation vivante¶

Proximite avec le code — la documentation doit être aussi proche que possible de ce qu'elle décrit. Une spec dans un wiki déconnecté du repo diverge. Un README dans le repo, des commentaires dans le code, des fichiers d'architecture dans le même dépôt : l'inertie organisationnelle favorise la cohérence.

Source de vérité unique — ne jamais documenter la même information en deux endroits. Tout doublon finira par diverger. Si l'information existe dans le code (schéma de base de données, contrat d'API, configuration), générer la documentation à partir du code, pas l'inverse.

Traçabilité des changements — la documentation doit évoluer avec les commits. Un changement d'architecture doit s'accompagner d'une mise à jour de la doc. Cela peut être impose par le Définition of Done ou par des outils de lint sur les pull requests.

Autorité établie — chaque document a un propriétaire responsable de sa pertinence. Sans propriétaire, personne ne se sent legitime pour corriger une inexactitude, et la documentation pourrit par inaction collective.

arc42 : un cadre pour l'architecture logicielle¶

arc42 est un template d'architecture logicielle en 12 sections standardisees, conçu pour produire une documentation concise et navigable. Contrairement a une approche narrative libre, arc42 impose une structure qui force l'équipe a répondre a des questions précises : quels sont les drivers architecturaux ? quels composants existent ? quelles décisions ont été prises et pourquoi ?

arc42 est compatible avec la méthode C4 pour les vues de composants (sections 5 et 6), et s'intégré naturellement dans un repo Git comme documentation as code.

Structurizr et C4 as code¶

Le modèle C4 (Context, Container, Component, Code) de Simon Brown fournit quatre niveaux d'abstraction progressifs pour visualiser une architecture logicielle. Son avantage clé : les diagrammes sont dérivés d'un modèle unique, garantissant la cohérence entre les niveaux.

Structurizr permet de définir ce modèle en code (DSL Structurizr ou SDK Java/C#/Python) et de générer les diagrammes à la demande. L'architecture devient un artefact versionne dans Git, soumis aux mêmes revues que le code.

workspace {
    model {
        user = person "Utilisateur"
        system = softwareSystem "Portail RH" {
            webapp = container "Application Web" "React + TypeScript"
            api = container "API REST" "Node.js / Express"
            db = container "Base de donnees" "PostgreSQL" "Database"
        }
        user -> webapp "Consulte ses donnees RH"
        webapp -> api "Appels REST / JSON"
        api -> db "Requetes SQL"
    }
    views {
        systemContext system "Contexte"
        container system "Conteneurs"
    }
}

Ce DSL généré des vues C4 coherentes, versionnable, diffable, et integrable dans une pipeline CI pour détecter les drifts d'architecture.

ADR : la mémoire decisionnelle¶

Pourquoi documenter les décisions¶

Un système technique est la somme de milliers de décisions. La plupart sont implicites : elles ne sont pas documentees, juste implementees. Quand une nouvelle personne rejoint l'équipe, quand un bug surgit six mois plus tard, quand il faut revenir sur un choix — personne ne sait pourquoi cette décision a été prise, ni quelles alternatives ont été evaluees.

L'Architecture Décision Record (ADR) répond a ce problème. Chaque décision architecturale significative est documentee dans un fichier court et structure, versionne dans le repo. Le résultat n'est pas seul documente : le contexte, les alternatives, les compromis et les conséquences le sont aussi.

La valeur de l'ADR n'est pas dans la décision elle-même — c'est dans le raisonnement. Quand l'équipe envisage de revenir sur un choix, elle peut voir pourquoi il avait été fait et évaluer si les conditions ont change.

Structure d'un ADR¶

Un ADR suit généralement le template de Michael Nygard :

# ADR-0042 : Adoption de PostgreSQL comme base de donnees principale

## Statut
Accepte

## Contexte
Nous avons besoin d'une base de donnees relationnelle pour les donnees metier.
Le volume prevu est de 10M de lignes avec des jointures complexes.
L'equipe maitrise SQL. Le projet doit etre deploye on-premise et en cloud.

## Decision
Nous adoptons PostgreSQL 15 comme base de donnees principale.

## Alternatives considerees
- MySQL 8 : moins de features JSON, communaute plus petite pour les features avancees
- SQLite : inadapte a un usage multi-utilisateur en production
- MongoDB : inadapte au modele relationnel de nos donnees metier
- Oracle : cout de licence prohibitif, vendor lock-in fort

## Consequences
Positives :
- Support natif JSONB pour les schemas flexibles
- Extensions riches (PostGIS, pg_vector, etc.)
- Open source, pas de license cost

Negatives :
- L'equipe devra monter en competence sur les specificites PostgreSQL
- Hosting manageable sur AWS (RDS), GCP (Cloud SQL), Azure (Flexible Server)

## Date
2024-03-15

## Auteurs
Alice Martin, Bob Dupont

Workflow ADR¶

flowchart LR
    A[Probleme technique\nidentifie] --> B[Redaction ADR\n— brouillon]
    B --> C[Revue en equipe\nPR / meeting]
    C -->|Rejet| D[ADR Rejete\narchive]
    C -->|Acceptation| E[ADR Accepte\nmerge dans main]
    E --> F[Implementation]
    F --> G[Revue periodique\ntous les 6-12 mois]
    G -->|Toujours valide| G
    G -->|Obsolete| H[ADR Deprecie\nnouveau ADR cree]

Les statuts standard d'un ADR : Propose, Accepte, Rejete, Deprecie, Remplacé par ADR-XXXX.

Stockage et organisation¶

Les ADR vivent dans le repo du composant qu'ils concernent, dans un dossier docs/decisions/ ou adr/. La convention de nommage : NNNN-titre-kebab-case.md. La numerotation séquentielle garantit un ordre clair et des références stables.

Pour les décisions transversales a plusieurs systèmes (choix de framework, politique de versioning des API, stratégie de sécurité), un repo de documentation central ou un espace wiki dédié est preferable, avec des références croisees depuis les repos concernes.

Runbooks : l'intelligence opérationnelle¶

Définition et structure¶

Un runbook est un document opérationnel qui décrit comment répondre a une situation spécifique en production : une alerte, un incident type, une procédure de maintenance. Il ne remplacé pas la compétence humaine — il la renforce en formalisant ce que les experts savent implicitement.

Un bon runbook structure la réponse en phases claires :

1. Symptomes et contexte

• À quelle alerte ce runbook correspond-il ?
• Quels sont les indicateurs observes (métriques, logs) ?
• Quelle est la sévérité typique ?

2. Diagnostic

• Commandes a exécuter pour confirmer le problème
• Métriques a consulter dans Grafana / Datadog
• Requêtes de log pertinentes

3. Actions de remédiation

• Étapes ordonnées avec les commandes exactes
• Points de décision (si X alors Y, sinon Z)
• Actions d'urgence vs actions de fond

4. Escalade

• À quel moment escalader ?
• Qui contacter ? (avec rotation d'astreinte)
• Canal de communication (Slack, PagerDuty)

5. Post-action

• Étapes de vérification post-remédiation
• Informations a collecter pour le post-mortem
• Actions de suivi a planifier

Automatisation partielle des runbooks¶

Un runbook entièrement manuel est lent et source d'erreurs sous pression. L'automatisation progressive réduit le temps de résolution (MTTR) et la charge cognitive sur l'astreignant.

Outils pour les runbooks automatises : AWS Systems Manager Runbooks, Opsgenie Runbooks, PagerDuty Process Automation, Rundeck, ou des workflows GitHub Actions declenches par webhook.

Lien avec l'alerting¶

Un runbook sans alerte est un document. Une alerte sans runbook est une alarme sans instruction. Les deux doivent être lies : chaque alerte Prometheus, chaque monitor Datadog, doit pointer vers son runbook via un lien dans l'annotation.

# Exemple d'alerte Prometheus avec lien runbook
- alert: HighErrorRate
  expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.05
  for: 5m
  labels:
    severity: critical
  annotations:
    summary: "Taux d'erreur eleve sur {{ $labels.service }}"
    runbook_url: "https://wiki.interne/runbooks/high-error-rate"
    description: "Le taux d'erreur 5xx depasse 5% depuis 5 minutes"

Revue périodique des runbooks¶

Un runbook vieillit. Les commandes changent, les services evoluent, les contacts d'escalade sont mutes. Un runbook obsolète en plein incident est pire qu'aucun runbook — il envoie l'astreignant dans la mauvaise direction.

La revue périodique doit être ritualisee : tous les trimestres minimum, ou après chaque incident ou le runbook a été utilisé. L'idéal est de joindre la revue du runbook au post-mortem de l'incident qui l'a déclenché — la mémoire est fraiche et les corrections évidentes.

Post-mortems : apprendre des incidents¶

La blameless culture¶

Le post-mortem n'est pas une chasse aux sorcières. Son objectif est systemique : comprendre comment le système a permis qu'un incident se produise, pas identifier le coupable humain qui a "fait une erreur".

La blameless culture (popularisee par Google SRE et Etsy) repose sur un postulat : les individus prennent les meilleures décisions possibles avec les informations et les outils disponibles au moment de l'incident. Si une mauvaise décision a été prise, le système — ses outils, ses processus, ses informations — a manque à sa mission de prévenir cette erreur.

Un post-mortem blame-aware provoque l'effet inverse : les équipes cachent les incidents, minimisent les détails genant, et n'apportent pas de vraies solutions par peur des conséquences personnelles. La blameless culture crée un environnement ou les incidents sont partages avec tous les détails pertinents, et ou les actions correctives sont substantielles.

Structure d'un post-mortem¶

Résumé executif — Quoi, quand, combien de temps, impact (utilisateurs touches, revenu impacte, données affectees).

Timeline — Reconstruction chronologique précisé des événements : première détection, actions prises, décisions, résolution. Inclure les timestamps. Distinguer les faits des interpretations.

Impact — Métriques d'impact : durée du service dégradé, pourcentage d'utilisateurs touches, volume de transactions échouées, données potentiellement corrompues.

Analyse des causes profondes (Root Cause Analysis) — Ne pas s'arrêter à la cause immédiate ("un développeur a pousse un code defectueux"). Utiliser la méthode des "5 pourquoi" pour remonter aux causes systemiques : pourquoi ce code defectueux a pu atteindre la production sans être détecté ? Pourquoi les tests n'ont pas couvert ce cas ?

Actions correctives — Liste des actions concrètes, avec responsable nomme et date de completion. Distinguer les actions immédiates (hotfix, mise à jour runbook) des actions long terme (ajout de tests, refactoring, nouveaux monitoring).

Ce qui a bien fonctionne — Les éléments qui ont limite l'impact ou accéléré la résolution. Renforcer ce qui fonctionne autant que corriger ce qui a failli.

Publication et suivi¶

Le post-mortem doit être publie, non range dans un tiroir. Une publication interne (wiki, Confluence, Notion) accessible à toute l'entreprise normalise les incidents comme source d'apprentissage.

Le suivi des actions est le point où la plupart des organisations échouent. Les actions sont identifiées, jamais implementees. Un backlog dédié aux actions de post-mortem, révisé en sprint review, avec un owner technique, est le minimum. Les actions sans owner et sans deadline ne seront pas faites.

Intégration dans les rituels DevOps et SRE¶

Knowledge sharing en sprint review¶

La sprint review n'est pas uniquement une demo de features. C'est aussi un moment de partage de connaissances techniques. Intégrer systematiquement un slot "ce qu'on a appris ce sprint" : une technique découverte, un problème résolu de façon intéressante, une configuration optimisee.

Ce ritual de 5 a 10 minutes par sprint accumule un capital de connaissance significatif sur l'année. Il normalise l'apprentissage comme activité cœur de l'équipe, pas comme une activité marginale pour "quand on à le temps".

Documentation dans le Définition of Done¶

La documentation n'est pas optionnelle — c'est un critère de completude. Le Définition of Done (DoD) de chaque équipe doit inclure :

Un DoD qui inclut la documentation crée une pression positive : la story n'est pas "done" tant que la connaissance n'est pas capturalisee. C'est une friction productive qui evite l'accumulation de dette documentaire.

Rotation des on-call comme vecteur de connaissance¶

L'astreinte (on-call) est souvent vecu comme une contrainte. Elle est aussi une opportunité de diffusion de connaissance : les personnes en astreinte apprennent rapidement les parties du système qu'elles ne connaissent pas.

Une rotation bien organisée :

• Fait tourner toute l'équipe, y compris les juniors (avec un escalade vers les seniors)
• Exige une session de passation de 30 minutes entre l'astreignant sortant et entrant
• Encourage la mise à jour des runbooks en fin d'astreinte
• Inclut un "wrap-up" hebdomadaire des incidents et quasi-incidents

La knowledge map de l'équipe est un outil complementaire : un tableau indiquant qui connait quoi, avec un niveau de maîtrise (novice, pratiquant, expert). La rotation on-call est conçu pour réduire les zones rouges (une seule personne experte).

flowchart TD
    subgraph Sprint["Cycle sprint (2 semaines)"]
        A[Planning\nKM items integres] --> B[Dev + Documentation]
        B --> C[Sprint Review\nSlot knowledge sharing]
        C --> D[Retrospective\nFrictions documentaires]
        D --> A
    end

    subgraph OnCall["Cycle on-call"]
        E[Passation\n30 min briefing] --> F[Astreinte active\nRunbooks + alerting]
        F --> G[Incidents\nPost-mortems]
        G --> H[Wrap-up\nMise a jour runbooks]
        H --> E
    end

    subgraph ADR["Decisions architecturales"]
        I[Decision identifiee] --> J[ADR redige\nen revue PR]
        J --> K[Merge + implem]
        K --> L[Revue periodique\ntous les 6 mois]
        L --> I
    end

    B --> I
    G --> J

Onboarding technique : intégrer sans perdre¶

Le coût de l'onboarding mal structure¶

Un onboarding mal structure crée deux problèmes. Pour la nouvelle personne : des semaines de flottement, de questions répétées, de code compris en surface sans comprendre les "pourquoi". Pour l'équipe : du temps senior consomme en support non planifie, des interruptions de flow, et une transmission de connaissances erratique dependant de qui est disponible.

Une estimation raisonnable du temps avant autonomie complète varie de 3 mois pour un système simple à 12 mois pour un système legacy complexe. Investir dans la structure de l'onboarding réduit ce délai significativement.

Parcours d'intégration structure¶

Un parcours d'intégration technique se decompose en trois phases :

Phase 1 : Orientation (semaine 1-2)

• Setup de l'environnement de développement (documentation pas-a-pas, testée régulièrement)
• Accès aux outils, repos, wikis, canaux Slack
• Vue d'ensemble de l'architecture (session avec un senior, diagramme C4 niveau Context et Container)
• Premiers commits sur des tickets de faible impact (bonne first issue)

Phase 2 : Immersion (semaine 3-8)

• Pairing systematique sur des tickets de complexité croissante
• Lecture des ADR des 12 derniers mois pour comprendre l'histoire des décisions
• Participation a une astreinte en observation (shadow on-call)
• Participation a un post-mortem en tant qu'observateur

Phase 3 : Autonomie (mois 3-6)

• Tickets de complexity moyenne en autonomie avec revue de code
• Première astreinte en titular (avec escalade disponible)
• Contribution à la documentation (au moins un document mis à jour ou créé)
• Session de retour sur l'onboarding pour améliorer le parcours

Buddy system et shadowing¶

Le buddy system assigne un pair (non hierarchique, idealement quelqu'un de 6 a 18 mois d'anciennete dans l'équipe) pour accompagner la nouvelle personne pendant les 4 premiers mois. Le buddy n'est pas un formateur — c'est un guide disponible pour les questions du quotidien que l'on n'ose pas poser au tech lead.

Le shadowing structure (observation d'un expert en situation réelle) est particulièrement efficace pour les compétences opérationnelles : shadow on-call, shadow pendant un deploy de production, shadow pendant une incident response. L'apprentissage par observation directe est irreplacable pour les connaissances tacites.