Les documents

Traditionnellement, du moins en France, la documentation d'architecture (DA dans la suite) est restée au paradigme du papier et donc de Word. Ca pourrait être pire, je ne sais pas moi du Powerpoint ? Ah mes condoléances.

Dans une activité qui devrait être un peu exemplaire en terme d'innovation, ce point m'a toujours gêné. Mais pour avoir essayer plusieurs fois, il est tout bonnement impossible de faire bouger ces lignes.

Quel est le problème d'une documentation sous Word ?

la mise à jour est au mieux aléatoire
la mise à jour n'est jamais coordonnée. Imaginons que vous ajoutiez un flux entre une application A et une application B. Il y a 99% de chances que le document de l'application A soit mis à jour mais que celui de l'application B ne soit pas modifié. A l'évolution suivante, ce sera l'inverse et la divergence va s'aggraver.
la pesanteur : ouvrir un word prend de plus en plus de temps, surtout si vous devez en ouvrir 10 pour trouver la bonne information
la difficulté d'interroger la documentation: si votre responsable vous demande "Tu peux me sortir la liste des applications possédant des données confidentielles et hébergées chez Rouge ?". Vous faites comment ? Vous ouvrez un à un l'ensemble de vos Words ?
la mise à jour du modèle. Votre modèle de documentation va sans cesse évoluer : par exemple, à l'arrivée d'une nouvelle réglementation comme le RGPD, ou bien lorsque les offres de service de votre SI, de votre hébergeur changent, ou encore si votre nouvelle politique d'architecture demande de nouveaux pré-requis à chaque dossier. Ces évolutions, tout à fait justifiées, vont se traduire par un surcroît de travail pour les rédacteurs de la DA, travail, passionnant qui plus est, à base de copier-coller. Autant dire qu'il ne sera jamais fait.

Mais soyons honnêtes quels sont ces avantages ?

Tout le monde peut le lire et le modifier comme bon lui semble (ce qui est aussi un problème)
Le suivi de modifications marche correctement, et parfois il fonctionne aussi en simultané sur un même document si vous avez une machine 16 cores 64 GO de RAM capable de faire tourner les solutions Office 365 bien entendu.
Le format se stocke facilement dans les système de Gestion Electronique de Document déjà existant dans l'entreprise.

Quelle serait la solution idéale ?
J'aime bien procéder ainsi lorsque je dois concevoir une solution : imaginer une solution parfaite, regarder si elle est applicable en l'état et au fur et mesure retrancher des choses pour parvenir à un résultat de plus pragmatique. Ici la solution parfaite devrait offrir un découplage complet entre fond (information structurées ou non) et forme (site web, PDF, etc). Au delà même de documenter, il devrait permettre de générer facilement ce qui est nécessaire au déploiement de la solution : flux réseaux à ouvrir, machines à approvisionner.
Elle devrait bien sûr être étroitement interfacée avec la solution de schémas. Elle devrait bien sûr être Open-source avant de ne pas dépendre d'un éditeur, on parle quand même du patrimoine intellectuel de l'entreprise sur le long terme ici. Cette documentation serait aussi gérée en version avec le code (lorsqu'il existe en interne dans l'entreprise)
En résumé, je me suis rendu compte que, sur le modèle de ce que fait un outil comme Terraform pour le déploiement, je voudrais tendre vers de la documentation qui produise à la fois des sorties (PDF, demande d'approvisionnement) mais aussi des donnée (pour pouvoir être requêté). Bref, il faudrait de la documentation-as-code.

J'ai eu beau cherché, je n'ai pas trouvé de solutions adaptées sur le marché. N'ayant pas eu ni le temps ni les ressources pour le développer, j'ai cherché des alternatives plus simples (des Quick-Wins comme ils disent)

Mes sources d'inspiration ont été

Terraform, l'outil d'Infrastructure as code pour ce formalisme qui permet de décrire en détail une solution technique
Readthedocs.io pour sa capacité à aller chercher l'information là où elle est (dans le dépôt du code concerné)
Mitre Att&ck pour son ergonomie de consultation.