L'approche de haut niveau que j'adopte généralement lorsque je documente des architectures (ou même des conceptions plus détaillées, de niveau inférieur) est :
- Identifier les parties prenantes de la conception. L'équipe d'ingénierie / de développement est l'une des parties prenantes. Votre équipe de test / assurance qualité, l'équipe d'infrastructure informatique, la gestion de projet, et peut-être le personnel de soutien peuvent également être des parties prenantes du système et s'intéresser à divers aspects de la conception.
- Identifier les domaines de préoccupation dans votre système. Si votre système a une base de données, un point de vue est la structure de la base de données. Si vous avez un système distribué, alors les administrateurs du système ou le personnel du service client peuvent être intéressés par l'endroit où les composants sont installés. Si vous avez une interface publique, alors les développeurs externes sont intéressés par ce qu'est cette interface - formats de fichiers, formats de données, etc. Si vous avez de nombreux algorithmes complexes, les concepteurs et mainteneurs d'algorithmes s'intéressent aux flux de travail et aux étapes des algorithmes. Chaque point de vue que vous identifiez est un ensemble spécifique de préoccupations.
- Pour chaque point de vue que vous avez, choisissez une représentation appropriée. Pour votre point de vue de base de données, peut-être des diagrammes entité-relation et un dictionnaire de données peuvent être utiles. Pour les interfaces publiques, les documents de schéma XML ou la documentation API peuvent faire partie de votre documentation. Pour les algorithmes complexes, pensez aux diagrammes UML de synthèse d'activité ou d'interaction. Lorsque vous choisissez une notation, je préfère les notations bien connues et bien définies afin de ne pas avoir à expliquer ma notation à quelqu'un d'autre et de pouvoir simplement lui indiquer le matériel de référence existant s'il ne connaît pas les symboles utilisés.
- Ajouter des descriptions textuelles et rationnelles autour des diagrammes. Expliquez non seulement quelles étaient les décisions architecturales que vous avez prises, mais aussi ce qui vous a poussé à prendre ces décisions.
Les cadres architecturaux, tels que le cadre Zachman, le cadre architectural de l'Open Group, le cadre architectural du ministère de la Défense et d'autres cadres architecturaux aident en définissant les points de vue essentiels et les points de vue qui sont généralement applicables.
En fin de compte, "la meilleure" documentation est celle qui répond aux besoins des parties prenantes. Identifier qui a besoin de l'information et ce dont ils ont exactement besoin est la première étape.
.