Les péchés capitaux du Dossier d'Architecture Technique

Cet article fait suite à mon précédent article :

Le dossier d'architecture technique, un dinosaure numérique ?

Un Dossier d'Architecture Technique (DAT) reste une documentation complexe à rédiger. L'articulation entre toutes les données techniques que l'on pourrait y déposer est essentielle pour sa lecture.

Les mêmes erreurs reviennent fréquemment dans les DAT que j'ai consulté.
Dans cet article, je voulais vous partager les erreurs majeures identifiées et proposer comment les éviter.

Sommaire :

• Créer un document unique
• Un DAT séparé de la documentation d'équipe
• Une seule personne responsable de son édition
• Une rédaction en début de projet ou une absence de révision
• Mélanger les niveaux d'architecture
• Ne pas utiliser un vocabulaire cohérent
• Copier-coller les procédures d'installation
• Référencer des documents inaccessibles
• Négliger les schémas d'architecture
• Conclusion

1. Créer un document unique

Il est surprenant que la majorité des modèles et exemples de DAT proposent un document unique, souvent au format Microsoft Word ou équivalent.

À l'ère de la documentation collaborative, rédiger un volumineux document Word contenant des pages de documentation technique et des copier/coller de contenu de documents existants n'est vraiment pas optimal/idéal.

Si nous avons abandonné les architectures monolithiques pour les applications, pourquoi les conserver pour la documentation ?

Pourquoi est-ce une erreur ?

Cette approche présente plusieurs inconvénients :

• Complexité excessive de la hiérarchie des titres
• Format inadapté à la lecture sur écran
• Déséquilibre entre les sections
• Manque de flexibilité pour la spécialisation des parties
• Difficulté d'évolution
• Recherche d'information complexe
• Collaboration limitée

Comment y remédier ?

Heureusement, on a inventé (en 1965) le lien Hypertexte.

Un dossier d'architecture peut et doit constituer une structure de pages et sous-pages.

Privilégiez les liens ou références vers les documents existants plutôt que de dupliquer les informations.

2. Un DAT séparé de la documentation d'équipe

Cette situation est souvent une conséquence directe de l'utilisation d'un document unique.

Pourquoi est-ce une erreur ?

Cette séparation crée une redondance dans l'effort de documentation.

L'équipe travaille avec une documentation collaborative (Wiki, Confluence, etc.) et doit maintenir parallèlement un autre document distinct dont ils n'ont pas l'usage.

Le DAT devrait faire partie intégrante de la documentation des équipes, car il vise principalement à répondre à leurs questions.

Principe : Si une documentation n'a pas d'utilité concrète, ne l'écrivez pas...

Le DAT porte les références techniques décrivant :

• Les éléments techniques en place
• Leurs relations
• Leurs contraintes
• Leurs périmètres

L'erreur consiste à le percevoir uniquement comme un livrable pour la mise en production, exigé par les équipes d'exploitation sans valeur ajoutée pour l'équipe solution.

Mais pourquoi est-il réclamé par les équipes d'exploitation ?

Les équipes d'exploitation le demandent car elles ne connaissent pas votre plateforme : elles ont besoin de comprendre les éléments techniques qui la constituent.

Et c'est précisément à cette question que le DAT doit répondre :

"Je ne connais pas la plateforme, comment est-elle construite ?"

Comment y remédier ?

Construisez (et maintenez) le DAT avec deux questions à l'esprit.
"Quels sont les éléments composant ma solution technique ?"
"Quelle est leur configuration pour que la solution fonctionne ?"

Le DAT sert à partager la connaissance :

• Pour les nouveaux arrivants dans l'équipe
• Pour les intervenants et équipes externes
• Pour les anciens eux-mêmes, afin de se remémorer leurs réalisations antérieures

Recommandation : Demandez aux nouveaux membres de l'équipe de mettre à jour et critiquer le DAT.

Cet exercice permet de confronter la documentation à la réalité.

3. Une seule personne responsable de son édition

El Famoso Architecte Omniscient qui voit tout le projet et ses spécificités techniques et mettra le DAT à jour correctement en conséquence n'existe malheureusement pas.

Pourquoi est-ce une erreur ?

L'effort de documentation doit correspondre à la réalisation technique.

Pour documenter efficacement, il est nécessaire d'avoir participé à la réalisation.

Une personne externe devra soit documenter avec des imprécisions, soit solliciter constamment les équipes de réalisation.

Comment y remédier ?

L'architecture et sa documentation sont l'affaire de tous.

L'ensemble des équipes, build et run, participent à l'effort documentaire.

Simon MAURIN vous convaincra mieux que moi en juste 15 minutes :

(youtube) Talk Devvox 2023 "Tous architectes ! (Simon MAURIN)"

4. Une rédaction en début de projet ou une absence de révision

C'est souvent le cas quand le DAT est créé en amont, lors de la phase de cadrage comme document de planification de la future architecture.

Pourquoi est-ce une erreur ?

En amont du projet :

• Des questions restent en suspens
• Des problématiques demeurent cachées
• Les décisions documentées peuvent devenir obsolètes
• Les sections concernées restent marquées "à faire"

Ne pas réviser la documentation existante équivaut à l'abandonner.

Comment y remédier ?

Le DAT doit vivre avec la plateforme qu'il décrit, pendant toutes les phases de build ET de run.

Planifiez des révisions régulières de la documentation, incluant le DAT.

Cette approche permet également de traiter la dette documentaire.
Établissez un plan d'action et planifiez-le : c'est un effort sur le long terme.

5. Mélanger les niveaux d'architecture

(petit rappel des niveaux d'architecture existants)

#	Architecture ...	Vue...	Outils
1	...d'entreprise	...stratégique	TOGAF
1bis	...de données	...données	structure et flux de données
2	...fonctionnelle	...métier	Specs fonctionnelles
3	...applicative	...logicielle	diagrammes de classe, etc
4	...technique	...infra & système	...
5	...réseau	...réseau	matrice de flux

L'architecture solution peut englober les niveaux données, fonctionnelle et applicative.

Dans ce cas, l'architecture réseau est généralement intégrée dans l'architecture technique.

Pourquoi est-ce une erreur ?

Mélanger différents concepts ne permet pas d'apporter des réponses précises.

Exemple inadéquat :

"L'architecture est une architecture n-tiers composée d'une webapp Java et d'une base de données Azure Database dans Azure"

Questions sans réponse :

1. Quel est le moteur de base de données utilisé ?
2. Dans quel composant s'exécute la webapp ?

Version améliorée :

"L'architecture est une architecture n-tiers composée d'une webapp Java et d'une base de données PostgreSQL.
La webapp Java s'exécute dans une image Docker sur un Azure App Service.
La base de données PostgreSQL est hébergée sur une Azure Database dans Azure."

Comment y remédier ?

• Respectez le niveau d'architecture décrit et sa terminologie
• Formez les équipes à ces concepts fondamentaux
• Chaque responsable doit décrire son périmètre de manière simple et précise

6. Ne pas utiliser un vocabulaire cohérent

C'est une erreur fréquente et compliquée à corriger.

Pourquoi est-ce une erreur ?

La communication est compromise lorsque :

Des termes différents désignent les mêmes composants :

• Header / En-tête / Bandeau
• Gateway / Passerelle / Proxy / Reverse proxy
• Backend / Serveur / API / Services
• Machine virtuelle / VM / Instance / Serveur virtuel
• Container / Conteneur / Pod / Instance Docker

Des acronymes sont utilisés sans définition :

• DR (Disaster Recovery, Data Retention, Design Review, Daily Report)
• MS (Microsoft, Microservice, Millisecond)
• RC (Release Candidate, Resource Controller, Remote Control)
• WAF (Web Application Firewall, Workflow Automation Framework, Windows Authentication Framework, Well Architectured Framework)
• BDD (Base de données, Behavior-driven development)
• DDD (Domain-driven design, Data display debugger dans gdb)

Des termes génériques utilisés sans autre précision :

• Flux (de données, de workflow, RSS, réseau, financier, d'intégration, d'évènement, utilisateur)
• Interface (API, graphique, réseau, communication)
• Service (microservice, Windows, métier, cloud, support)
• Instance (machine virtuelle, classe, base de données, processus)
• Client (projet, service, navigateur web, poste utilisateur)
• Agent (programme autonome, support technique, monitoring, sécurité)

Bref, tout simplement parce que chacun a son langage et ses codes et qu'il est pertinent de parler le même au sein de la même documentation.

Comment y remédier ?

Établissez un glossaire pour harmoniser la terminologie technique utilisée dans la documentation.

7. Copier-coller les procédures d'installation

Trop souvent, j'ai vu un DAT rempli avec la procédure d'installation.

Pourquoi est-ce une erreur ?

Des pages de captures d'écran avec des instructions basiques :

• Compliquent la lecture
• Rendent la recherche d'information fastidieuse
• Augmentent inutilement le volume du document

Un DAT n'est pas conçu pour héberger les procédures.

Comment y remédier ?

Externalisez les procédures du DAT dans des documents distincts.

Utilisez par exemple les dossiers documentaires spécifiques :

• Dossier d'Installation (DIN)
• Dossier de Montée de Version (DMV)

8. Référencer des documents inaccessibles

"Retrouvez le document sur Z:\DSI\Procédures-exploitation\DEX-APP.docx"

"Lien https://sharepoint/deleted_user/DAT-APP.docx"

Le drame de trouver ce genre de document, posé sur un espace restreint accessible uniquement par les N2 de l'équipe d'exploitation "mais là ils sont en récupération de l'astreinte HNO de la nuit, faut repasser demain ou faites un ticket".

Ou bien dans le onedrive partagé du prestataire venu faire l'installation de l'outil il y a 3 ans et déjà reparti ...

Pourquoi est-ce une erreur ?

Simplement parce que "Accès refusé" n'est pas l'information que vous recherchez.

Comment y remédier ?

• Vérifiez l'accessibilité des documents référencés
• Placez chaque solution IT dans son propre espace documentaire
• Assurez l'accès aux équipes concernées
• Vérifiez régulièrement la validité des liens

9. Négliger les schémas d'architecture

Des mauvais schémas d'architecture, voire pas de schéma du tout.

C'est sans doute l'erreur la plus importante pour la compréhension de la solution :

Un schéma d'architecture fournit :

• Une cartographie des composants
• Leurs relations
• Leurs limites et frontières

De mon expérience, c'est généralement l'information principale recherchée dans un DAT.

Pourquoi est-ce une erreur ?

Un schéma illisible avec :

• Une taille excessive
• Des liens qui se croisent
• Des traits de même couleur
• Une mise en page confuse

crée plus de confusion que de clarté.

"Une image vaut 1000 mots."

"Un bon dessin vaut mieux qu'un long discours."

Comment y remédier ?

Faites des schémas !
schéma d'architecture, UML, de base, de classe, de séquence, d'intégration, de déploiement, ...

• A tous les niveaux (d'architecture)
• A tous les niveaux (de détail)

Conseils pratiques :

• Utilisez des outils modernes (draw.io, Lucidchart, Cacoo)
• Exploitez les solutions de Diagram-as-Code (Mermaid, PlantUML)
• Pour les schémas d'infrastructure Terraform, explorez Brainboard

Conclusion

Voila un petit florilège des erreurs les plus grossières que j'ai rencontré (oui, je les ai toutes eues plusieurs fois).

Ces corrections permettront d'améliorer votre DAT et de réduire votre dette documentaire.

Certaines modifications peuvent s'avérer complexes, impliquant des changements :

• Politiques
• Organisationnels
• De communication
• De formation

"Keep it simple" : Optimisez l'utilisation des outils à votre disposition.

Dans les prochains articles, je parlerais de plusieurs armes pour vous aider à remédier à ces erreurs et l'article final vous proposera un guide pour y remédier.

Cet article fait partie du "Advent of Tech 2024 Onepoint", une série d'articles tech publiés par Onepoint pour patienter jusqu'à Noël.
Voir tous les articles du Advent of Tech 2024

Merci de votre lecture !