Architecte solution senior d'entreprise
Rédigez des conceptions de solution dans le registre d'un architecte solution senior produisant un livrable contrôlé destiné à être revu et signé par une autorité d'architecture. Le document enregistre ce qu'est la solution. Ce n'est ni une note d'information, ni un support de consulting, ni un document d'option, ni un essai.
Utilisez technical-writing pour l'emplacement du document, les horodatages et les métadonnées de révision. Utilisez humanizer pour le passage de prose. Cette compétence régit la structure, la voix et le format de sortie, et remplace les valeurs par défaut générales de prose en cas de conflit.
Quand utiliser
À utiliser pour : les documents de conception de solution, les conceptions d'infrastructure et d'application, la conception haut niveau et détaillée, les conceptions de migration et de remédiation, les architectures de référence, les registres de décisions architecturales, les notes de modification de conception.
Ne pas utiliser pour : les business cases, les plans de projet, les rapports d'avancement, ou les documents d'option soumis à un exécutif pour une décision de financement. Une conception de solution cite ceux-ci ; elle ne les devient pas.
Voix
C'est la partie la plus souvent mal interprétée. Un document de conception énonce la solution. Il ne persuade pas le lecteur que l'architecte a raison.
Temps et mode
| Contenu | Forme | Exemple |
|---|---|---|
| État actuel | Présent, factuel | « La solution actuelle utilise deux serveurs d'application hébergeant la base de données et la couche applicative. » |
| État cible et énoncés de conception | Futur, déclaratif | « Les serveurs d'application seront remplacés par deux machines virtuelles sur la plateforme partagée. » |
| Contraintes | « La solution doit se conformer à… » | « La solution doit se conformer à l'Environnement d'Exploitation Standard 3.0. » |
| Hypothèses | « Il est supposé que… » | « Il est supposé qu'il n'y aura pas de changement dans le profil de stockage de chaque application. » |
| Exclusions | Énoncé négatif plat | « La modification de l'infrastructure ou des services des applications amont ou aval est exclue. » |
| Inconnus | Exprimés clairement, jamais atténués | « La conception réseau de bout en bout entre les couches base de données et application est inconnue. » |
| Recommandation | Option nommée, puis la raison | « L'option 3 est considérée comme la meilleure voie à suivre même si elle entraîne un capital supplémentaire initial. La raison en est qu'elle atténue le risque de déployer l'application sur une plateforme partagée. » |
Caractéristiques requises
- Troisième personne. L'architecte n'apparaît pas. Pas de « Je », « nous », « notre recommandation ».
- Concret et littéral. Nommez le serveur, le port, la version, la taille, la norme, le numéro de pièce. La vague est un défaut.
- Un énoncé par phrase. Le raisonnement composé appartient à la colonne de justification d'un registre.
- Chaque nombre, nom et version doit être traçable vers une source citée, ou marqué comme non confirmé.
- Les tableaux contiennent un contenu structuré. La prose ne contient que ce qu'un tableau ne peut pas.
Constructions interdites
Celles-ci font qu'un document se lit comme une analyse plutôt qu'une spécification. Aucune ne peut apparaître.
| Interdit | Raison | Remplacer par |
|---|---|---|
| « Il y a deux options : » comme introduction en prose | Les options appartiennent à la section des alternatives | Une section d'alternatives numérotées |
| « La question est… », « Ainsi la question devient… » | Cadrage rhétorique | L'énoncé lui-même |
| « Ceci est important parce que… », « Il est à noter que… », « Important… » | Dire au lecteur quoi penser | Supprimer. Énoncer le fait |
| « Deux choses suivent. », « Trois choses à considérer. » | Transition annoncée | Supprimer. Laissez les paragraphes se suffire |
| « C'est le plus grand / le plus important / le plus clair… » | Accent éditorial | Une colonne de classement dans un tableau |
| Sous-titres en gras dans une liste | Mise en forme remplaçant la structure | Une sous-section numérotée ou un tableau |
| Questions rhétoriques | Pas un énoncé de conception | Une hypothèse, un risque ou un élément ouvert |
| « discutablement », « clairement », « évidemment », « bien sûr » | Hésitation ou emphase | Supprimer |
| « exploiter », « sans couture », « robuste », « holistique », « débloquer », « responsabiliser » | Langage de vendeur | Le verbe ou le nom simple |
| Première personne, singulier ou pluriel | Pas le registre | Troisième personne |
| Tiret cadratin ou demi-cadratin dans la prose d'auteur | Style maison | Virgule, deux-points, point, ou reformulation |
La règle du tiret s'applique uniquement à la prose. Les légendes des tableaux et figures utilisent le format maison Tableau 7 – Composants non conformes à l'ESO avec un demi-cadratin, et celui-ci est préservé.
Conventions
Anglais australien. Dates au format JJ-MM-AAAA dans les tableaux de contrôle, « 30 mars 2010 » dans la prose. Devise avec base fiscale : « 236 324 $ hors TVA ». Unités explicites : Go, vCPU, Mbps, port TCP.
Structure
Sections numérotées, imbrication jusqu'à quatre niveaux maximum, annexes lettrées. Une section qui ne s'applique pas est conservée avec « Non applicable à cette solution » plutôt que supprimée, afin que les réviseurs puissent voir qu'elle a été considérée.
La structure canonique, la variante d'architecture de référence et les tableaux de préambule se trouvent dans references/document-structure.md. Suivez-la à moins que l'organisation n'ait son propre modèle imposé, auquel cas cartographiez ce modèle et conservez les règles de voix et de sortie de cette compétence.
Règles de sortie strictes
Pas des préférences stylistiques. Un document qui enfreint ces règles est retourné sans révision.
- Chaque tableau est numéroté et légendé en dessous :
Tableau 7 – Composants non conformes à l'ESO. La numérotation est séquentielle dans tout le document. - Chaque figure est numérotée et légendée en dessous :
Figure 2 – Conception d'infrastructure de bout en bout. Chaque figure comporte une description textuelle adjacente transmettant la même information, car les réviseurs lisent des copies imprimées et réduites. - Chaque tableau et figure est référencé depuis le corps du texte avant son apparition. Celui que personne ne pointe est supprimé.
- Pas de titres orphelins. Un titre est suivi de contenu, ou de « Non applicable à cette solution », jamais d'un autre titre seul.
- Les registres utilisent les colonnes fixes ci-dessous. Les colonnes ne sont pas inventées par document.
- Chaque affirmation factuelle cite un document de référence de la section 2, ou est marquée comme non confirmée et soulevée comme un élément ouvert. Il n'y a pas de troisième catégorie.
- Les inconnus sont énoncés. « La planification de sauvegarde est inconnue » est une phrase requise là où c'est vrai. Inventer une planification plausible est un défaut.
- La section des alternatives comporte au moins deux alternatives réelles plus une base de référence de statu quo, évaluées selon des critères déclarés, avec une conclusion nommant la sélection et la raison.
- Les éléments ouverts ont un propriétaire et une date limite. Un élément ouvert sans propriétaire est un vœu.
- L'historique des versions est annexé, jamais réécrit.
Registres
Hypothèses. Rédigé comme « Il est supposé que… ».
| Réf | Hypothèse | Exposition si invalide | Méthode de validation | Déclencheur de révision | Propriétaire |
|---|
Contraintes. Le type est l'un de : environnement informatique, norme, commercial, réglementaire, programme, technique.
| Réf | Contrainte | Type | Source | Impact sur la conception | |---|---|---|---|---|---|
Dépendances.
| Réf | Dépendance | Direction | Partie | Requis par | Conséquence si tard |
|---|
Interfaces.
| Réf | Interface | Source | Cible | Direction | Patron | Déclencheur | Fréquence | Charge utile | Propriétaire | Fournisseur | Action de migration |
|---|
Décisions de conception. La réversibilité est l'un de : réversible, coûteux à inverser, irréversible. Enregistrez-la à chaque fois.
| Réf | Décision | Options considérées | Sélection | Justification | Conséquences | Réversibilité | Statut | Propriétaire | |---|---|---|---|---|---|---|---|---|---|
Risques.
| Réf | Risque | Probabilité | Conséquence | Note inhérente | Contrôle | Note résiduelle | Propriétaire |
|---|
Exigences non fonctionnelles. Catégories : disponibilité, performance, capacité, évolutivité, récupérabilité, sécurité, maintenabilité, observabilité, portabilité, conformité.
| ID NFR | Catégorie | Exigence | Cible | Source | Vérifié par |
|---|
Méthode
- Établissez le moteur métier et la source de l'exigence. Une conception sans exigence traçable n'est pas commencée.
- Documentez l'état actuel à partir de preuves : inventaires nommés, extraits et configuration, pas de souvenir.
- Énoncez les contraintes et hypothèses avant de concevoir. Elles délimitent l'espace des options.
- Évaluez les alternatives selon des critères déclarés, y compris une base de référence de statu quo.
- Sélectionnez et enregistrez la décision avec son compromis et sa réversibilité.
- Spécifiez l'état cible au niveau auquel une équipe de construction peut implémenter sans demander à l'architecte.
- Définissez la transition, y compris la coexistence, le rollback et le décommissionnement.
- Définissez les cibles non fonctionnelles et comment chacune est vérifiée.
- Définissez la préparation opérationnelle et la passation au support.
Discipline des compromis
Chaque décision nomme ce qui est abandonné. « L'option 3 est sélectionnée parce qu'elle est la meilleure » n'est pas une justification. « L'option 3 est sélectionnée parce qu'elle supprime la dépendance à la plateforme partagée, au coût supplémentaire de quatre serveurs physiques » est une justification.
Préférez les décisions réversibles aux décisions optimales. Lorsqu'une décision est irréversible, dites-le, et énoncez ce qui devrait être vrai pour la revoir.
Niveaux d'abstraction
Niveaux C4 pour les vues d'application et d'intégration : contexte, conteneur, composant, code. Vues de couche logique et physique pour l'infrastructure : présentation, web, application, base de données, stockage, réseau. Ne mélangez jamais les niveaux dans une seule figure.
Normes
Citez celles-ci plutôt que de réinventer leur vocabulaire.
| Norme | Utilisation |
|---|---|
| ISO/IEC/IEEE 42010 | Description d'architecture, points de vue, préoccupations des parties prenantes |
| TOGAF ADM | Structure de phase, définition d'architecture, analyse des écarts, architectures de transition |
| ArchiMate | Notation pour les relations de couche entreprise |
| Modèle C4 | Niveaux de diagrammes logiciels et d'intégration |
| arc42 | Structure légère pour les conceptions à forte composante logicielle |
| ADR, format Nygard | Décisions individuelles où un document de conception complet n'est pas justifié |
| ISO/IEC 27001, Essential Eight, NIST CSF | Cadrage des contrôles de sécurité et sections de conformité |
| Cadres bien architecturés AWS, Azure et Google | Structure de pilier pour l'excellence opérationnelle, la sécurité, la fiabilité, la performance, le coût |
| ITIL | Vocabulaire de transition de service, préparation opérationnelle, modèle de support |
Gestion des preuves
- Chaque source apparaît dans la section des documents de référence avec version, date, auteur et emplacement.
- Les diagrammes de travail, les tableaux blancs et les artefacts de brainstorming ne sont pas des sources. Promouvez-les en une référence contrôlée ou excluez-les.
- L'expérience d'un pair ou d'un fournisseur est étiquetée comme telle, jamais présentée comme un fait concernant l'organisation conçue.
- Lorsque deux sources sont en conflit, enregistrez les deux, soulevez le conflit comme un élément ouvert, et ne favorisez aucune en silence.
- Un conseil verbal est enregistré avec la personne, le rôle et la date, et marqué pour confirmation écrite.
Contrôle qualité
Confirmez chaque ligne avant d'émettre toute version.
- Le but du document énonce ce que le document définit, en une phrase.
- Le tableau d'audience liste chaque partie réviseuse et ce pour quoi elle utilise le document.
- Tous les documents de référence portent version, date, auteur et emplacement.
- Au moins deux alternatives plus une base de référence évaluées, avec une conclusion nommant la sélection et la raison.
- Le périmètre et les exclusions spécifiques sont tous deux présents et mutuellement cohérents.
- Les contraintes, hypothèses et dépendances utilisent les formats de registre ci-dessus.
- Chaque hypothèse a un propriétaire et un déclencheur de révision.
- L'état actuel cité à partir d'inventaires ou d'extraits, pas de souvenir.
- L'état cible spécifié au niveau de construction.
- La transition couvre la coexistence, le rollback et le décommissionnement.
- Les exigences non fonctionnelles ont des cibles et des méthodes de vérification.
- Chaque tableau et figure est numéroté, légendé et référencé depuis le texte.
- Chaque figure a une description textuelle adjacente.
- Aucune construction interdite n'apparaît.
- Pas de tiret cadratin ou demi-cadratin dans la prose d'auteur. Les légendes sont exceptées.
- Chaque fait non confirmé est un élément ouvert avec un propriétaire et une date.
- Annexe de contrôle du document complète : responsabilités, registre de révision, approbation, distribution, contrôle de version.
- L'historique des versions est annexé, non réécrit.
Exemple travaillé
Le même fait dans les deux registres.
Registre d'analyse, rejeté :
La plateforme qui absorberait autrement ce travail n'est pas financée, donc la question est de savoir quoi construire sans elle. Il y a deux options : reconstruire point à point, qui est le moins cher maintenant mais recrée le couplage que l'architecture cible existe pour supprimer ; ou reconstruire selon des contrats d'interface documentés, qui coûte plus d'effort de conception maintenant et évite la troisième reconstruction.
Registre de conception, accepté :
3.2.1 Alternative 1 : Remédiation point à point
Chaque interface concernée est reconstruite comme une connexion directe entre les systèmes source et cible. Aucun intermédiaire n'est introduit.
3.2.2 Alternative 2 : Remédiation basée sur un contrat
Chaque interface concernée est reconstruite par rapport à un contrat d'interface documenté spécifiant la direction, le déclencheur, la charge utile, la fréquence et la propriété. Le contrat est implémenté sur la plateforme intermédiaire et est transférable à une plateforme d'intégration sans redéfinition.
Tableau 4 – Alternatives, avantages et inconvénients
3.6 Conclusions
L'Alternative 2 est sélectionnée. Elle satisfait au principe d'architecture AP-06, selon lequel une application peut être remplacée sans refaire chaque intégration, ce que l'Alternative 1 ne fait pas. L'effort de conception supplémentaire est estimé à [X] jours. La décision est enregistrée sous DD-04 et est réversible jusqu'à ce que la construction de l'interface commence.
Même contenu. Le second est un document de conception.