# Documenter une architecture logicielle --- ## Tour d' horizon de notre documentation * fichers .md (Mermaid: UML, sequence diagram etc.) * Document sur le Google drive: slides, texte, draw * les pdfs en PJ (Wrike, Gmail) * excalidraw * figma * Notion * export image, photo de tableau * ... Note: Regroupons ces supports par --- ## Group by | plain text | binaires | | -------- | -------- | | .md | Google draw | | .txt | Google slides | | | pdf | | | excalidraw | | | figma | | | Notion | Note: Pourquoi avoir choisi ces critères ? Cela donne un fort indice quand à la maintenabilité. vendor lock-in ? Collaboration Versionning / diff Heritage / réutilisation La notation va nous garantir que nous modélisons dans les mm rails. --- ## Evaluons notre documentation Critères: * indice d'audience (large ?) * indice de maintenabilité * vendor lock in * moment (conception, post mortem, comprendre un bug, suivre le traitement d'une information, risk management, étudier des évolutions architecturales, identifier les spof etc.) --- ## Recap | --------------- | plain text | binaires | | --------------- | ------------------ | ---------------- | | audience | :heavy_check_mark: | :man-shrugging: | | maintenabilité | :heavy_check_mark: | :x: | --- ## Simon Brown --- ## Simon Brown * lauréat du "IEEE Software sponsored" 2013: conflict between agile and architecture * consultant pour aider les professionnels du logiciels à décrire leur architecture.  --- ## C4 model * approche pragmatique et non académique * notation independent * tooling independent * encourage l'écriture de diagram as code|plain text * offre différentes visualisations à partir d'une même description d'architecture logicielle --- ## 4 couches d'abstraction  --- ## Des vues à volonté * Projeter des vues personalisées selon un scope et une audience * décrire le "deployment" --- ## Demo https://structurizr.com/ --- ## Conseils pour réussir sa doc * Commencer par documenter la couche haute avant d'aller plus loin: * identifier les **person** * identiier les **softwareSystem** * décrire les **relations** entre les person et softwareSystem * Ne documenter surtout pas la couche code, votre IDE sait déjà le faire pour vous et vous ne l'utilisez pas car le use case est rare. * structurer votre DSL (commentaires, includes, extensions) --- ## Doc as Code CI/CD  note: exemple gitlab ima protect push vers cloud gestion utilisateurs par workspace review interactive etc ... --- ## Bonus * héberger sa doc le le :cloud: * support de theme (icon, font, colors etc.) * visualiser ses ADRS * visualiser sa doc Markdown|AsciiDoctor --- ## Finalement Après 2 semaines d'utilisation et avoir testé cette approche sur ima-protect, cadiou et qwertys, je recommande ce shampoing: * 4 (couches) en 1 (notation) * démêlant * ne pique pas les yeux * évite les noeuds  --- ## Références * [Official website](https://c4model.com/) * [C4 models as code - Simon Brown - NDC Oslo 2023](https://www.youtube.com/watch?v=4HEd1EEQLR0) * [Structurizr language reference](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md) * [DSL playground](https://structurizr.com/dsl) * [PR Cadiou Inductries](https://github.com/le-phare/cadiou-extranet/pull/176) * [MR ima-protect](https://gitlab.com/groupeima/partenaire/imaprotect-lephare/infrastructure/-/merge_requests/6) * [1h de conf sur le plain text (masterclass)](https://www.youtube.com/watch?v=gd5uJ7Nlvvo)