Cas avances¶

Documentation pour la conformité, les organisations multi-équipes, les décisions techniques et la mesure de la qualité documentaire.

Documentation pour la conformité¶

Les certifications de sécurité et de conformité imposent de produire, maintenir et conserver des documents spécifiques. La documentation ops joue un rôle central dans cette démarche.

ISO 27001¶

L'ISO 27001 exige une documentation formelle autour du Système de Management de la Sécurité de l'Information (SMSI). Les documents clés cotes exploitation :

HDS (Hebergement de Données de Sante)¶

La certification HDS ajoute des exigences spécifiques aux acteurs traitant des données de sante :

• Procédures d'exploitation documentees et accessibles aux auditeurs
• Traçabilité des accès aux systèmes hebergeant des données de sante
• Documentation des sauvegardes et de leur vérification
• Plan de reprise d'activité teste et documente

SOC 2¶

SOC 2 (Type II) nécessité de prouver que les contrôles sont actifs en continu sur une periode d'observation. Les preuves documentaires incluent :

• Logs d'audit de tous les accès privilegies
• Évidence des revues périodiques de sécurité
• Documentation des changements de configuration avec approbation

Documentation multi-équipes¶

Dans les organisations ou plusieurs équipes partagent une infrastructure ou des systèmes communs, la documentation nécessité des conventions explicites.

Conventions partagees¶

Ownership distribué¶

Dans une organisation avec ownership distribué (chaque équipe est responsable de ses services), la documentation suit la même logique :

• Chaque équipe maintient la documentation de ses services
• Les éléments transversaux (réseau, sécurité, IAM) ont un owner central
• Un comite ou un "docs champion" coordonné les conventions globales

Inner source doc¶

L'approche inner source applique les pratiques open source à la documentation interne : n'importe quel membre de l'organisation peut proposer une amélioration via un pull request. Les equippes proprieetaires font la revue.

Cela nécessité :

• Un dépôt Git accessible à toute l'organisation
• Un processus de PR clair et rapide (pas de bureaucratie)
• Une culture de la contribution qui valorise les améliorations

ADR infra : Architecture Décision Records¶

Un ADR (Architecture Décision Record) documente une décision technique significative : le contexte qui l'a motivee, les options evaluees, la décision prise et ses conséquences.

Quand écrire un ADR¶

• Choix d'un hyperscaler ou d'un outil structurant
• Changement de stratégie de backup ou de DR
• Migration d'un service critique vers une nouvelle technologie
• Choix d'une approche de sécurité (zero trust, VPN, PAM)
• Toute décision dont on imagine "on va en reparler dans 18 mois"

Template ADR infra¶

# ADR-XXX : Titre court et descriptif

Date : YYYY-MM-DD
Statut : Propose | Accepte | Deprecie | Remplace par ADR-YYY
Decideurs : Noms ou equipes

## Contexte

Quel probleme ou besoin a motive cette decision ?
Quelles contraintes etaient presentes ?

## Options evaluees

| Option | Avantages | Inconvenients |
| ------ | --------- | ------------- |
| Option A | ... | ... |
| Option B | ... | ... |

## Decision

Quelle option a ete retenue, et pourquoi ?

## Consequences

Quelles sont les implications de cette decision ?
Quelles dettes techniques ou contraintes en decoulent ?

Métriques de qualité documentaire¶

Mesurer la qualité d'une base documentaire permet de piloter son amélioration de façon objective.

graph LR
    A["Inventaire doc"] --> B["Calcul fraicheur"]
    B --> C["Mesure couverture"]
    C --> D["Analyse usage"]
    D --> E["Plan d'amelioration"]
    E --> A

Indicateurs clés¶

Collecte des données¶

• Fraicheur et couverture : script sur le dépôt Git (date du dernier commit par fichier)
• Liens morts : markdown-link-check dans la CI
• Usage : analytics du site de documentation (Plausible, Google Analytics, logs serveur)
• Satisfaction : retour d'expérience post-incident ("le runbook etait-il utile ?")