Dans le chapitre précédent, nous avons vu ce qu'est une documentation d'architecture et à quoi ça sert, ainsi que quelques exemples.
Dans ce chapitre, nous allons voir comment correctement identifier les besoins des parties prenantes du projet, afin de créer la documentation adaptée.
Qui sont les parties prenantes ?
Sur tous ces groupes, seuls quelques-uns liront votre documentation. Appelons cette fraction votre « public ».
Écrivez pour votre public
Il est maintenant temps de vous demander : Qui va lire ma documentation ? Pour qui allons-nous écrire ces documents ?
Au moins pour les groupes suivants :
Développeurs.
Administrateurs de bases de données.
Ingénieurs en génie logiciel.
Architectes logiciels.
Le tableau suivant décrit, pour ces groupes de parties prenantes, ce dont ils ont besoin et ce que doivent être notre style et notre contenu :
Notre public | Ses besoins | Style à adopter | Contenu nécessaire |
Développeurs | Architecture générale de la solution, exigences fonctionnelles, structure des bases de données, structure des fichiers. | Très technique, utilisation de schémas. | Structure des dossiers, structure des fichiers, structure des bases de données. |
Administrateurs de bases de données | Architecture générale de la solution, utilisation attendue du système, caractérisation des utilisateurs. | Très technique, utilisation de schémas. | Structure des fichiers, description hiérarchique des fichiers, relations entre fichiers, description des index. |
Ingénieurs en génie logiciel ou Architecte logiciel | Architecture générale et détaillée de la solution, exigences fonctionnelles, structure des bases de données, structure des fichiers. | Très technique, utilisation de schémas, référence à un glossaire des termes. | Description de la solution, principales fonctionnalités du système, courte description de la structure des bases de données et des fichiers. |
Exemple 1 : adaptez votre documentation
Cet exemple illustre l'embauche d'ingénieurs en génie logiciel expérimentés, en relation avec le tableau ci-dessus. Imaginez que votre entreprise s'apprête à développer un système logiciel en interne sans embaucher de développeurs externes pour ce projet. Il lui faudra pourtant impérativement embaucher un prestataire externe : le projet nécessite la compétence d'ingénieurs expérimentés en génie logiciel, spécialisés en sécurité du stockage et du transfert de données. Or, l'entreprise ne possède ni ces connaissances, ni cette expérience.
Ces prestataires spécialistes de la sécurité des données auront besoin d'une documentation technique du système extrêmement détaillée. Ils l'utiliseront pour développer leur solution. Vous et votre équipe devez rédiger un document spécifique à leur intention.
Autre documentation ? Il y a déjà beaucoup de code ici…
Exemple 2 : les administrateurs de bases de données sont, eux aussi, des parties prenantes
L'exemple suivant porte sur la communication avec les administrateurs de bases de données de votre équipe, en relation avec le tableau ci-dessus. Imaginez que vous deviez expliquer aux administrateurs de bases de données comment fonctionne votre système et comment il sera développé.
La conception de la base de données du système est un moment absolument crucial, puisque cette base de données constituera le socle de votre système : une fois créée, elle supportera tout l'édifice et sera très difficile à modifier.
Voici les informations nécessaires pour les administrateurs de bases de données :
Quelles sont les principales tables du système ? (Clients, produits, utilisateurs du système, éléments des produits, tables générales, etc.)
De quelle façon les tables sont-elles dépendantes les unes des autres ? (Un client peut-il avoir plusieurs produits ? Les éléments des produits dépendent-ils de la table des produits ?, etc.)
Comment les utilisateurs effectueront-ils des recherches dans les tables ? (par ID client, par nom de client, par ID de produit, etc.)
Réutilisez des éléments de documentation
Les architectes logiciels et les développeurs sont des gens paresseux. 🙂 Ils n'ont aucune envie d'écrire deux fois le même document. Vous allez devoir utiliser les mêmes schémas et les mêmes dessins dans de nombreux documents.
Voici quelques exemples de modules de base utiles et réutilisables :
Description générale de la solution.
Interfaces avec d'autres systèmes.
Description des principales fonctionnalités du système, du point de vue de l'utilisateur.
Description générale des tables et des index des bases de données.
Schéma général de la sécurité du système.
En résumé
La partie prenante d'un projet est une personne, un groupe ou une entité qui peut avoir une influence sur un projet ou être influencé par celui-ci. Exemples : chef de projet, équipe projet, direction générale, client d'un projet, responsable de gamme, sous-traitant, consultant ou autre employé de l'entreprise.
Écrivez pour votre public : développeurs, administrateurs de bases de données, ingénieurs logiciels, architectes logiciels.
Adaptez votre documentation : au besoin, rédigez des documents spécifiques à l'intention de certains groupes de parties prenantes. Vous gagnerez du temps et vous éviterez les malentendus.
Réutilisez des éléments de documentation : vous allez devoir utiliser les mêmes schémas et les mêmes dessins dans de nombreux documents. Documentez certains modules de base et identifiez-les soigneusement avant de commencer à rédiger l'ensemble de la documentation.
Dans le chapitre suivant, nous allons voir quelques bonnes pratiques pour représenter votre documentation, ainsi que des exemples concrets.
