vlaskos/architecture-documentation-skill

Documenter les architectures logicielles

La documentation d'architecture sert à répondre aux questions que les parties prenantes vous poseront autrement en réunion pendant toute la durée de vie du système : Comment cela est-il assemblé ? Pourquoi est-ce ainsi ? Où dois-je modifier X ? Cela tiendra-t-il sous Y ? Une bonne documentation répond à ces questions une fois pour toutes, par écrit, sous une forme que chaque lecteur peut réellement utiliser.

Cette compétence est une méthode pour produire cette documentation, et pour réviser la documentation écrite par quelqu'un d'autre. Elle repose sur des normes et modèles ouverts et librement disponibles, non sur un texte protégé par le droit d'auteur :

• ISO/IEC/IEEE 42010 — la norme internationale pour la description d'architecture. Elle fournit le vocabulaire utilisé partout : partie prenante, préoccupation, point de vue, vue, modèle, décision d'architecture, justification.
• Le modèle C4 (Simon Brown) — un ensemble léger de diagrammes structurels à quatre niveaux de zoom : contexte, conteneur, composant, code.
• Le modèle 4+1 (Philippe Kruchten) — cinq perspectives concurrentes : logique, processus, développement, physique, et les scénarios qui les relient.
• arc42 — un modèle de documentation sous licence Creative Commons dont la structure en sections constitue un squelette pratique pour une description d'architecture complète.
• Architecture Decision Records (le format ADR popularisé par Michael Nygard) — un fichier court par décision importante.

La méthode

La documentation est pilotée par qui la lit et par ce dont ils ont besoin pour décider ou agir. Travaillez dans cet ordre.

1. Identifier les parties prenantes et leurs préoccupations. Listez qui dépend de l'architecture (développeurs, exploitants, relecteurs de sécurité, propriétaires de produit, intégrateurs, auditeurs) et ce que chacun attend de la documentation. Une préoccupation est une question ou une qualité qui importe à quelqu'un : « puis-je déployer cela sans interruption de service ? », « où vivent les données clients ? », « comment ajouter un nouveau fournisseur de paiement ? ». Les préoccupations déterminent tout ce qui suit. Voir references/viewpoints-and-views.md.

2. Sélectionner les points de vue qui couvrent les préoccupations. Un point de vue est une sorte de vue réutilisable : les conventions pour construire un type de représentation (quels éléments elle montre, quelles relations, quelle notation). Choisissez le plus petit ensemble de points de vue qui, ensemble, répondent à chaque préoccupation importante. N'écrivez pas de vue dont personne n'a besoin. Voir references/view-catalog.md.

3. Construire les vues. Chaque vue est une représentation du système depuis un point de vue : un diagramme et le texte qui l'explique. La plupart des systèmes ont besoin d'une vue structurelle (quels sont les composants et comment ils dépendent les uns des autres), d'une vue d'exécution (ce qui se passe au moment de l'exécution : processus, flux, interactions), et d'une vue de déploiement (comment le logiciel est mappé à l'infrastructure). Ajoutez des vues comportementales pour les parties où le séquencement ou le timing est essentiel. Les niveaux C4 et les perspectives 4+1 sont des moyens concrets et éprouvés pour les peupler. Voir references/view-catalog.md.

4. Capturer les décisions et leur justification. La partie la plus précieuse — et la plus souvent absente — de la documentation d'architecture est le pourquoi. Enregistrez chaque décision importante (le contexte, les options envisagées, le choix retenu et ses conséquences) comme un Architecture Decision Record. La justification permet à la personne suivante de modifier le système en toute sécurité plutôt que de deviner. Voir references/decisions-and-rationale.md.

5. Assembler la description et ajouter des repères. Un tas de vues n'est pas un document. Ajoutez le tissu conjonctif : un résumé du système en une page, un énoncé du périmètre et du contexte, un glossaire, et une note explicite sur la façon dont les vues sont liées entre elles (le même élément vu dans deux vues est la principale source de confusion pour le lecteur — clarifiez-le). Utilisez references/documentation-template.md pour un squelette complet de sections.

6. Réviser avant de publier. Passez la documentation au crible de references/review-checklist.md. Les deux modes d'échec sont l'incomplétude (une préoccupation qu'aucune vue n'adresse) et l'illisibilité (diagrammes sans légende, termes non définis, absence d'indication sur ce que le lecteur regarde).

Comment utiliser cette compétence

• Partir de zéro → suivez les six étapes ci-dessus, en utilisant references/documentation-template.md comme structure cible.
• Décider quoi écrire → references/viewpoints-and-views.md (préoccupations → points de vue) et references/view-catalog.md (le catalogue des types de vues).
• Enregistrer une décision → references/decisions-and-rationale.md (format ADR et exemples).
• Réviser une documentation existante → references/review-checklist.md.
• Choisir entre des cadres ou mapper l'un sur l'autre → references/frameworks-map.md.

Principes

• Écrire pour un lecteur, pas pour l'exhaustivité. Chaque vue, diagramme et paragraphe doit répondre à une préoccupation d'une partie prenante. Si vous ne pouvez pas nommer qui en a besoin, supprimez-le.
• Tout diagramme a besoin d'une légende. Une notation qui « semble évidente » ne l'est pas. Indiquez ce que signifient les boîtes et les lignes. Un diagramme non expliqué est une supposition qui attend de se tromper.
• Enregistrer la justification au fur et à mesure. Les décisions sont peu coûteuses à capturer au moment où vous les prenez et très chères à reconstituer plus tard.
• Rester proche du code et à jour. Une documentation qui dérive de la réalité est pire que pas de documentation, car les gens lui font confiance. Privilégiez un document plus petit que vous tiendrez à jour plutôt qu'un grand que vous ne tiendrez pas.
• Laisser le risque du système déterminer la profondeur. Documentez en détail les parties où une erreur est coûteuse ; esquissez le reste.