Les erreurs les plus communes du DAT que j'ai rencontrées

Un DAT reste une documentation complexe à rédiger.
L'articulation entre toutes les données techniques que l'on pourrait y déposer est essentielle.

Du coup, je rencontrais fréquemment les mêmes types d'erreurs dans les DAT que j'ai lu.

Dans cet article, je vous liste les plus grosses auxquels j'ai pensé et que faire pour les éviter.

Sommaire :

• Faire 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 le même vocabulaire/glossaire
• Copier-coller les procédures d'installation
• Faire des références vers des documents non disponibles
• Mauvais schéma d'architecture
• Conclusion

1/ Faire un document unique

À l'époque où (quasi) tout le monde utilise une documentation collaborative, faire un document unique, C'est vraiment une pratique à bannir.
Souvent un gros document .doc avec des pages et des pages de blabla technique et des copier-coller de docs existantes.

Trop dense, trop lourd :

• Complexité
• Besoin de spécialisation de certaines parties
• Évolutivité
• Difficulté de recherche
• Collaboration

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

==>

Un "dossier" d'architecture peut et doit être une structure de pages/sous-pages
Si un document autre contient des données, créez un lien ou une référence.
Ne réécrivez surtout pas les informations.
Et assurez-vous que les lecteurs puissent avoir accès aux documents référencés

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

Pourquoi le DAT serait séparé de la documentation des équipes ?
La rédaction d'un DAT a un but de répondre aux questions… des équipes.

Si la documentation n'a pas de but et ne sert pas, ne l'écrivez pas...

Le DAT porte les références techniques décrivant les éléments techniques en place, leurs relations, leurs contraintes et périmètres.

Oui, comme la documentation que vous produisez.

L'erreur, c'est qu'il est juste perçu par l'équipe projet comme un document livrable pour la Mise en Production, réclamé par les équipes d'exploitation.

Mais pourquoi est-il réclamé par les équipes d'exploitation ?
Ces équipes d'exploitation ne sont pas sur le projet et ne connaissent pas votre plateforme :
Ils veulent comprendre les éléments techniques qui constituent la solution déployée.

Et c'est précisément à cette question que le DAT doit répondre :
"Je ne connais pas la plateforme, comment est-elle construite ?"

==>

Construisez (et maintenez) le DAT avec ce but à l'esprit.
Il servira tout autant aux nouveaux arrivants dans l'équipe qu'aux intervenants et équipes extérieurs.

Demander aux nouveaux de l'équipe de mettre à jour/critiquer le DAT. ça permet de confronter la documentation et 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 en conséquence n'existe malheureusement pas.

==>

L'architecture et sa documentation sont l'affaire de tous.
Toutes les équipes, projet et run, doivent participer à l'effort.

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

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

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

Avant le projet, il reste toujours des questions en suspens, et des problématiques que l'on ne voit pas.
Soit les décisions inscrites vont devenir fausses, soit pire les paragraphes les mentionnant garderont une mention "todo".

==>

Le DAT doit vivre avec la plateforme qu'il décrit, pendant tous les projets de build ET le run.
Programmer des révisions régulières de la documentation, en incluant le DAT
ça permettra une résolution de la dette documentaire

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 englobe (ou peut englober) les niveaux d'architecture de données, fonctionnelle et applicative.

Dans ce cas, on intègre généralement l'architecture réseau dans l'architecture technique (principalement dans un souci d'équilibre des chapitres).

Mélanger différentes notions n'apporte pas une réponse précise.
Vous aurez des moitiés d'informations et devrez aller voir directement les composants techniques pour avoir votre réponse.

Exemple :

L'architecture est une architecture n-tiers composée d'une webapp Java et d'une azure database dans Azure

Question 1 : quel est le moteur de base de donnée employé ? mysql ? postgre ? sql server ?
Question 2 : Dans quel composant est exécutée la webapp ? vm, aks (kube azure), app service ?

Il aurait mieux valu écrire

L'architecture est une architecture n-tiers composée d'une webapp Java et d'une base de donnée postgre.
La webapp Java tourne dans une image docker sur un Azure App Service.
La base de donnée postgre est hébergée sur une Azure Dabase dans Azure

==>

Faire attention au niveau d'architecture décrit et aux termes associés.
Chacun est responsable de son périmètre et doit le décrire de manière simple et précise

Ce qui fait une bonne transition avec l'erreur suivante souvent liée

6/ Ne pas utiliser le même vocabulaire/glossaire

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

==>

Faire un glossaire pour s'aligner sur les termes techniques à employer 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.
Des pages et des pages de copie d'écran des actions "appuyez sur le bouton Next"

Un DAT n'est pas fait pour stocker les procédures.

==>

Sortir les procédures du DAT et mettre chaque procédure dans un document différent.

8/ Faire des références vers des documents non disponibles

"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 ...

==>

Vérifier et contrôler la portée des documents en référence.
Placer Une solution IT dans son propre espace documentaire dans lequel tous les documents associés sont placés et partagés aux équipes qui en ont besoin.

9/ Mauvais schéma d'architecture

Des mauvais schémas d'architecture, voire pas de schéma du tout.
Trop gros, plein de lien qui se croisent, des traits de la même couleur, ...

"Une image vaut 1000 mots."
"Un bon dessin vaut mieux qu'un long discours."

C'est sans l'erreur la plus importante :
Un schéma d'architecture apporte une cartographie et une implémentation des composants. Il permet de montrer la structure générale, les associations, limites et frontières entre chaque élément.

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

==>

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)

2 Astuces en plus :

• profitez des outils existants plus légers que Visio (draw.io, lucidChart, Cacoo, etc)
• Vous avez des solutions de Diagram-as-code (Mermaid pour le markdown par exemple) ou de génération de schéma
• pour les schéma d'infra+Terraform, vous avez des outils intéressants comme Brainboard qui généralisent le "je dessine un schéma, ça génère le code terraform".

Conclusion

En corrigeant déjà ces erreurs, vous réduirez votre dette documentaire et devriez retrouver un intérêt dans l'usage du DAT.

A noter : certaines ne sont pas simples à corriger (politique, silos, problèmes de communication et/ou de formation).

"Keep it simple" : Faites au mieux avec les outils dont vous disposez