L'outil de documentation

Introduction

L'objectif de cet article est d'apporter des informations sur comment utiliser l'outil de documentation et de décrire un processus de documentation utilisant les modèles de documents de EA.

Cet article indique comment :
Appliquer sa charte graphique à la documentation
Construire une documentation comprenant plusieurs sous-modèle chacun ayant sa présentation adaptée
Se souvenir d'un document en l'enregistrant comme ressource du projet

Construire une documentation structurée.

Un modèle n'a de sens que par rapport au type de dossier sur lequel il est appliqué. Ex: un modèle basé sur les uses cases devra être appliqué sur un répertoire "use case model".

On a besoin quand on lit un document produit à partir de EA de savoir quel modèle a été utilisé pour le produire.

Voici une solution à ce problème donnée par Patrick BACK

Créer un diagramme de documentation en choisissant dans la rubrique 'Extended" le type "documentation".

( Note : Comme on ne peut pas créer un diagramme à la racine d'un projet, la meilleur place de ce diagram est dans un répertoire "Project Model" où l'on place des éléments qui ne sont pas le modèle.)

La tool box associée par défaut à ce type de diagramme comprend trois outils :

• Master Document : correspond à un répertoire stéréotypé <<master document>>.
• Model Document : correspond à une classe que l'on va lier à un modèle par une tagged value.
• Document artifact : sert à inclure un document externe dans la documentation.

Ajouter sur le diagramme un objet de type "master document", il se matérialse par un répertoire stéréotypé <<master document>>. Créer un modèle de document à partir du modèle <<master document>> et lui appliquer la charte graphique souhaitée. (Note : Le travail de la charte graphique sera beaucoup plus aisé avec Word qu'avec l'outil d'édition des modèles. Il faut pour cela exporter le modèel, le travailler avec Word en le conservant en format .rtf puis le réimporter et faire save. Attention : quand on importe un fichier RTF, il s'importe dans le modèle encours d'édition dans EA et l'écrase. )

Associer ce modèle au répertoire master document en indiquant son nom dans la tagged value "RTFTemplate" du répertorie.

Aller ensuite dans le diagramme associé au master document et lui ajouter des "Model Document", un "Model DOcument" est une classe stéréotypée <<Model Document>>. Ce stéréotype de classe comporte comme la master document une tagged value qui permet d'associer un modèle. Le modèle sera choisi en fonction du type de répertoire que l'on inclure dans la classe pour être documentée.

On tire ensuite dans les classes les répertoires que l'on veut inclure dans la documentation. Ces références viennent se positionner comme attributs de la classe.

Gérer un niveau d'indépendance entre le modèle et un projet

L'onglet "Project constants" dans la forme de lancement de la génération de la documentation permet de définir des valeurs que l'on peut inclure. Pour inclure une valeur ( ex: nom du client, nom du prjet, interlocuteur) faire un clic droit à l'endroit de l'insertion, les valeurs disponibles sont proposées dans la rubrique "Project constants".

Se souvenir des documents cosntruits et ed leur modèles associés.

Le bouton "Resource document" de la forme de lancement de la génération de la documentation permet d'enregistrer le document comme une ressources du projet. On le retrouve ensuite dans le panneau " Project ressource" d'où on peut le consulter ou le regénérer. (Note : Il est possible qu'il y ait un problème avec le fichier de documentation généré si celui-ci se trouve sur le disque local. Que se passe-t-il si une autre personne essaie d'y accéder ?)