Cahier des  charges pour la Documentation du Logiciel AMDA

Le présent document décrit l'ensemble des documents à écrire pour réaliser une documentation complète et exhaustive du logiciel. Dans un processus normal de développement logiciel, la plupart de ces documents sont écrits avant la phase de codage. S'agissant d'un prototype, la documentation n'a pas été écrite avant, ni même durant cette phase de codage (ou partiellement).

Objectifs Affichés

• A court terme, permettre à une personne n'ayant pas participé au codage du logiciel de pouvoir maintenir le code, afin d'assurer la continuité du service rendu par AMDA.
• A moyen et long termes, permettre une évolution  du produit en fonction de nouvelles fonctionnalités à ajouter, de l'évolution des technologies, faciliter l'intervention de sous-traitants, et le transfert de connaissance des personnes ayant conçu le prototype vers d'autres personnes
• Identifier les parties à améliorer pour faciliter cette évolution.

Pour cela il est nécessaire d'avoir deux niveaux de documentation. Un haut niveau permettant d'avoir une connaissance générale du produit, de situer chaque module de développement dans l'architecture générale. Un deuxième niveau doit donner la possibilité d'intervenir dans le code source afin de maintenir et faire évoluer le produit

Documents à délivrer

Guide de l'Utilisateur

      Ce document est écrit principalement à l'intention des scientifiques devant utiliser AMDA. Mais il doit pouvoir servir de référence pour la description de ce que fait , ou permet de faire le logiciel. Il contient une description exhaustive de toutes les  fonctions du logiciel, mais n'entre pas dans les détails du "COMMENT".

Document de Spécification de besoin

Document de Conception préliminaire

Document de Conception détaillée

Unified Modelling Language (UML)

Pour faciliter la communication entre les différents interlocuteurs (scientifiques, développeurs, utilisateurs finaux) on convient d'utiliser le langage UML.

Le rédacteur pourra choisir le moyen le plus adapté, au cas par cas, parmi les outils disponibles au travers d'UML:

• Cas d'utilisation
• Diagrammes de classe
• Diagramme de Séquence
• Texte
  Une combinaison de ces différents modes de représentation étant souhaitable.

pour en savoir plus sur UML :   http://fr.wikipedia.org/wiki/Unified_Modeling_Language

Moyens

Commentaires généraux MG :

Il ne me semble pas opportun d'imposer un type de représentation pour cette documentation. C'est au rédacteur d'effectuer ce choix en fonction du sujet traité, et du niveau de détail requis pour la compréhension. Certaines parties  seront mieux  décrites par du texte , d'autres par des schémas ou les deux à la fois. De même concernant les outils. Le rédacteur devra s'assurer qu'ils sont aisément utilisables, de préférence libres de droit. Pour certains , une présentation , ou un tutoriel, succints permettront de les introduire. Enfin , c'est plutôt le formalisme utilisé qui importe plus que l'outil utilisé pour l'exprimer. A l'extrême limite, les schémas pourront être délivrés en PDF.

Il sera nécessaire de figer une version de AMDA pour cette documentation.

A plusieurs reprises a été exprimé le besoin de conserver une version opérationnelle du logiciel. Le "re-factoring" dont il a été question à plusieurs reprises se fera donc par modifications successives et non pas par le développement d'un nouveau produit à partir d'un cahier des charges établi en s'inspirant de l'expérience acquise avec le prototype. Il ne me semble donc pas opportun de parler de "AMDA-NG". (par analogie, SIPAD-NG est un produit différent du SIPAD, développé entièrement à partir d'une nouvelle spécification de besoins)

Il faudra aussi décrire comment ce travail se fera. Quelle est la "matière première" délivrée au rédacteur ? Je suppose que c'est l'ensemble du code source et de la documentation existante. Mais la disponibilité de la personne (Elena) ayant codé le produit me paraît indispensable. Peut-être est-il nécessaire de formaliser cela.

commentaires du code et génération de documentation

Attendu:

outil de génération de documentation à partir des commentaires du code source et autres fichiers de documentation comme les README du source.

Cela garantit une synchronisation systématique entre le code source et la documentation.

Solutions:

• doxygen: http://www.stack.nl/~dimitri/doxygen/
• docbook: http://www.gnome.org/projects/dia/

un outil pour exploiter les schémas UML

Attendu:

• pouvoir créer et modifier les schémas produits
• Ajout CJ édition de la visualisation des schémas par niveaux
• Ajout CJ traçabilité le long d'un process réponse MG: géré par cas d'utilisation et diagrammes de séquence
• Possibilité d'import et export de schémas en XMI (XML Metadata Interchange) . Cela permet de changer de logiciel en utilisant un format de sortie standard

Solutions pouvant être envisagées:

• umbrello, UML Modeler: http://docs.kde.org/stable/en/kdesdk/umbrello/index.html
• Visual Paradigm for UML (VP-UML) http://www.visual-paradigm.com/product/vpuml/
• ARGOUML http://fr.wikipedia.org/wiki/ArgoUML
• Dia, logiciel d'édition de graphiques: http://www.gnome.org/projects/dia/

Commentaires

-- MyriamBouchemit - 11 Dec 2007

La liste de la documentation à fournir me semble complète. Il faudrait programmer une réunion pour se répartir les tâches, je pense que les scientifiques sont les mieux placés pour rédiger le document de spécification de besoins et partiellement le guide utilisateur. Pour les autres documents, il faudrait regarder de plus près comment sont commentés les codes et s'il existe un début de documentation afin de faciliter le chiffrage de la rédaction des documents spécifiés.

-- MyriamBouchemit - 11 Dec 2007

-- CDPP.MichelGangloff - 11 Décembre 2007