Avant de voir directement comment documenter un système, voici ce que vous devez savoir :
à quoi sert la documentation ;
à quel moment créer une documentation pour les parties prenantes.
À quoi sert la documentation ?
Imaginez que vous construisiez une maison. Un grand nombre d'intervenants différents viendront travailler pendant un certain temps : maçons, électriciens, couvreurs, charpentiers, plombiers. Chacun d'eux connaît son travail et tous savent ce qu'ils ont à faire, mais ils ont en commun un besoin essentiel : il leur faut le plan du bâtiment pour pouvoir travailler. Ils l'utiliseront tous de façon différente, mais ils en ont tous besoin pour bâtir la maison ensemble !
L'utilisation de la documentation
La documentation de l'architecture sert le même objectif pour votre projet de logiciel. Vous devez décrire un même système pour plusieurs personnes qui parlent des langues différentes. Nous utilisons la documentation de l'architecture essentiellement :
Comme un contrat interne liant les parties prenantes du projet, c’est-à-dire des personnes, des groupes ou des entités qui peuvent avoir une influence, positive ou négative, sur votre projet, ou qui peuvent être influencés par celui-ci. Exemples : votre équipe, les promoteurs du projet, les fournisseurs externes, les utilisateurs de votre système ou d'autres services de votre entreprise. Pour pouvoir répondre aux attentes, un projet doit intégrer le travail de différentes parties prenantes à travers un accord. Cet accord implicite entre différentes parties internes de l'entreprise constitue un contrat interne.
Un outil de communication permettant de comprendre le cœur d'un système. L'objet d'un outil de communication dans un projet est d'aider un groupe de deux utilisateurs, ou davantage, à atteindre un but ou un objectif commun en travaillant ensemble. Le cœur d'un système est le groupe de qualités qui définit ce que fait ce système, la façon dont il le fait et pour qui il le fait, indépendamment de l'aspect qu'il revêt pour l'utilisateur.
La documentation vous permet de gagner du temps et d'instaurer une cohérence d'ensemble
Si la documentation de votre projet est incomplète ou inexistante, les groupes de travail ne comprendront pas le projet de la même manière, ce qui entraînera une mauvaise interprétation de la solution : certains d'entre eux partiront dans la mauvaise direction et devront rebrousser chemin. Cela fera perdre du temps et de l'argent au projet, et démotivera les membres de l'équipe.
De même, si vous ne possédez pas de documentation ou que celle-ci est incomplète, vous devrez décrire la solution à chaque nouveau membre de l'équipe et/ou fournisseur externe, cela à de multiples reprises. La documentation vous permet donc de gagner du temps et d'instaurer une cohérence d'ensemble.
Quand créer une documentation pour les parties prenantes ?
Vous vous demandez peut-être à présent à quel moment commencer à créer la documentation de l'architecture : avant le début du projet, au milieu ou une fois le projet terminé ?
Il y a deux étapes de votre projet logiciel au cours desquelles vous devez créer de la documentation :
lors de la phase de proposition du projet ;
lors de la phase de mise en œuvre du projet.
Phase de proposition du projet
Dans la phase de proposition, vous présentez une solution logicielle à des dirigeants ou des cadres de votre entreprise, qui vont vous écouter et décider d'investir ou non leur budget dans ce projet.
Les avantages en question sont en général ce que recherchent la plupart des entreprises : des ventes plus élevées, une meilleure efficacité, davantage d'économies. Les coûts engendrés par un projet sont la somme des embauches, des heures qu'y consacrent les salariés de l'entreprise, des achats de matériel et des dépenses spéciales qu'il entraîne.
Que faire dans cette phase ?
À ce stade, vous n'avez besoin que d'une documentation générale de l'architecture.
Ce document contient des termes non techniques ou à faible contenu technique qui doivent être compréhensibles par toutes les parties prenantes, notamment les promoteurs du projet et quelques autres dirigeants de l'entreprise. À ce stade, votre documentation est un outil d'analyse, de conception préliminaire et d'estimation des coûts.
Exemple réel n° 1
Voici un bon exemple de document général d'architecture logicielle, simple et facile à comprendre, issu d'un véritable projet : la mise en place d'une nouvelle section destinée à un groupe spécial d'utilisateurs sur le site web d'une entreprise.
Il pourra être judicieux de montrer ce schéma simple au conseil d'administration de l'entreprise au moment de présenter votre proposition de projet.
Phase de mise en œuvre du projet
La deuxième phase est celle de la mise en œuvre du projet.
Cette phase de mise en œuvre débute une fois votre projet « vendu ». Lorsque le projet est approuvé, vous avez besoin de la documentation comme outil de maintenance de la qualité et de gestion des attentes des clients.
Exemple réel n° 2
Il s'agit d'un schéma technique du schéma fonctionnel présenté ci-dessus, à utiliser dans le cadre de la mise en œuvre du projet :
Je ne veux pas vous effrayer avec des termes barbares ; je vais donc vous expliquer tous les libellés du schéma ci-dessus :
Pilote de base de données : éléments de code, fonctions et procédures permettant de connecter le site web à la base de données afin que les deux puissent dialoguer.
Structure de la table : description des tables, des champs, des types de champ et des tailles de champ de tout le système.
Description des index : spécifications des index, dérivées de recherches et de requêtes que le système effectuera couramment ; par exemple pour rechercher des clients à partir d'un numéro de client ou d'un nom de famille.
Procédures de requêtes : procédures d'insertion, de suppression et de mise à jour de toutes les tables de la base de données.
Pare-feu : système de sécurité du réseau qui surveille et contrôle le trafic réseau entrant et sortant, en fonction de règles de sécurité prédéterminées. Un pare-feu établit une barrière entre un réseau interne fiable et un réseau externe qui ne l'est pas, tel qu'Internet.
Zone démilitarisée (DMZ) : zone neutre servant à déposer et à prendre des fichiers, habituellement partagée par les utilisateurs externes et internes d'un système. Une DMZ sert à empêcher les utilisateurs d'accéder à un système interne.
Modèles de connexion : procédure de connexion, de vérification et d'authentification des utilisateurs.
Modèles de requêtes de bases de données : procédures de consultation de la base de données à utiliser par tous les programmeurs.
Modèles de performances : procédures visant à améliorer les performances d'un système, à utiliser par tous les programmeurs.
Modules de base écrans : fonctions qui manipulent les champs, les boutons et les cases à cocher de tous les écrans du système.
Modules de base rapports : fonctions qui manipulent des éléments de rapports tels que les en-têtes, les pieds de page, le corps, etc.
Modules de base graphiques : fonctions qui affichent des graphiques types, tels que des graphiques XY, des graphiques en secteurs, des fonctions de régression, etc.
Comment l'équipe utilise-t-elle la documentation d'architecture ?
Vous devez réunir une équipe, chercher à établir une collaboration entre différents services de votre entreprise et, peut-être, embaucher des prestataires ou des consultants externes. Comment expliquez-vous à chacun d'entre eux ce qu'est la solution et ce qu'il doit faire ? Cela n'est possible qu'à travers une documentation détaillée.
Si vous regardez le schéma technique ci-dessus, vous êtes censé réaliser des schémas encore plus détaillés de certains composants clés du schéma précédent : « Pilote de base de données », « Pare-feu », par exemple, devront être étudiés avec un niveau de détail encore supérieur et décrits chacun dans un schéma complet et distinct. Les développeurs et les concepteurs utiliseront ces schémas détaillés pour effectuer leurs tâches.
En résumé
La documentation est un contrat interne qui lie les parties prenantes, et un outil de communication qui permet de comprendre le cœur d'un système.
Rédigez une documentation complète. Cela évite les malentendus et fait gagner du temps.
Rédigez la documentation pour deux phases : la proposition de projet et la mise en œuvre du projet :
documentation générale de l'architecture pour la proposition de projet ;
documentation technique détaillée pour la mise en œuvre du projet.
Dans le prochain chapitre, nous verrons comment identifier ce que votre documentation doit contenir, en fonction des personnes qui la liront.
