Documentation de votre projet

La production de documentation est une tâche importante du développement de logiciels. Il n’y a pas de logiciel de qualité sans une documentation de qualité. Dans le cadre de votre projet, nous vous demandons de rendre un certains nombre de documents relatifs à votre application. Les documents à déposer sur la forge (dans l'onglet document) de votre projet sont les suivants :

1. Le cahier des charges (à rendre semaine 3);
2. Le cahier de recette (à rendre semaine 4);
3. La conception générale
4. La conception détaillée (à rendre semaine 5);
5. Le manuel d'utilisation (à rendre semaine 11);
6. Le manuel d'installation (à rendre semaine 11);
7. Le plan de tests (à rendre semaine 11);
8. La documentation interne du code (à rendre semaine 11).
9. Le code sources du programme (à rendre semaine 11);
10. Le rapport de projet (avant la soutenance);
11. Le résumé en français et en anglais (avant la soutenance);
12. Les diapositives sonorisées (avant la soutenance);

Sur la forge, la page wiki de chaque équipe doit être complétée au plus tard la veille de la soutenance. (voir FAQ/Comment rendre mon projet)

Il faudra également faire un tirage-papier de votre rapport en deux exemplaires à remettre au secrétariat au plus tard 48 heures ouvrables avant la soutenance.

Vous trouverez des modèles de documents à l'adresse suivante : Modèles de document

Le cahier des charges est un document rassemblant les obligations et les éléments nécessaires pour définir un besoin et les principales contraintes à respecter pour le satisfaire. Le cahier des charges est un élément objectif qui permet à un client de choisir son fournisseur. Les rubriques spécifiques du cahier des charges sont les suivantes :

1. Introduction
   1. Contexte : Décrire brièvement l’environnement dans lequel s’inscrit le projet (stratégie, enjeux, domaine, etc.)
   2. Historique : Donner un bref historique du contexte dans lequel s’inscrit le projet
2. Description de la demande
   1. Les objectifs : Définir les résultats que le projet doit atteindre
   2. Produit du projet : Proposer une description générale de ce produit
   3. Les fonctions du produit : Lister et justifier les principales fonctionnalités du produit
3. Contraintes
   1. Contraintes de délais : Spécifier la date de livraison du produit et les éventuelles échéances intermédiaires
   2. Contraintes matérielles : Spécifier le matériel nécessaire au bon fonctionnement du produit
   3. Autres contraintes : Spécifier les éventuelles contraintes à prendre en compte dans le cadre du projet (normes techniques, clauses juridiques, etc.)
4. Déroulement du projet
   1. Planification : Représenter les grandes phases du projet et les étapes principales
   2. Ressources : Lister les ressources humaines et matérielles
   3. Organisation : Décrire l’ensemble des activités introduites dans l’organigramme des tâches de la gestion de projet (Décomposition en tâches, Structure des équipes)

Modèle de document : Modèle de cahier des charges

La recette est la phase de livraison de tout ce qui a été réalisé durant le projet, elle se décompose en 3 étapes. Le cahier de recette va décrire le contexte, et le détail du déroulement de ces étapes.

1. Soumission
   • Remise de l'application (cd, clé usb, dépôt CVS, …)
   • Remise des documents liés au projets (nature, format, …)
2. Vérification
   • Environnement de test
   • Ensemble des tests à réaliser
3. Validation
   • Décisionnaire

L'ensemble des tests va permettre de valider le bon comportement fonctionnel de l'application du point de vue du client. Ces tests permettent à l'équipe de développement de définir ses objectifs fonctionnels et ainsi de savoir comment sera évaluée son application. A l'issue de la recette, selon que l'application passe correctement l'ensemble des tests, le client peut accepter ou refuser l'application. Étant donné leur importance, ces tests doivent être définis dans le détail.

Dans un cycle de développement en V, la phase de recette est symétrique de la phase de spécification. Normalement, c'est le client qui doit rédiger son propre cahier des charges ainsi que son cahier de recette; mais dans notre cas de figure ce n'est pas le cas; cela présente l'intérêt de vous aider à comprendre ce qui est attendu du point de vue fonctionnel en vous mettant en partie à la place du client. Dans la phase de spécification vous devrez répondre à la question :

• Quelles sont les fonctionnalités souhaitées par le client ?

Dans la phase de recette vous devrez répondre à la question :

• Comment le client déterminera que l'application livrée fera bien ce qui était souhaité ?

Ainsi, pour chaque fonctionnalité définie dans le cahier des charges, on trouvera un ensemble de tests accompagné de critères de validation dans le cahier de recette.

Modèle de document : Modèle de cahier de recette

La conception générale est la phase de modélisation de l'application à réaliser. Dans le document de conception générale, on doit retrouver :

• la description des grands domaines fonctionnels
• l'architecture de l'application
• les interactions des éléments décrits avec les autres éléments (internes et externes)

Le paradigme du langage de programmation envisagé pour réaliser l'implémentation détermine la description de l'architecture envisagée. Le document de conception générale doit lister les packages, les modules, les interfaces, les classes… ainsi que leurs interactions avec d'autres composants de l'application comme avec les composants externes (librairies, systèmes, serveurs, capteurs, …)

Dans la plupart des cas, le formalisme UML est recommandé.

Modèle de document : A venir

La conception détaillée affine la conception générale en présentant toutes les fonctions, méthodes, classes, paquetages, librairies,… qui seront nécessaires au bon développement de l'application.Ce document vise à faciliter l'implémentation de votre application par les développeurs et vise à garantir que le fonctionnement de l'application correspondra bien aux besoins de l'utilisateur final.

Ce document est organisé en fonction de l'architecture de l'application, en répétant autant de fois que nécessaire les rubriques suivantes. Pour chaque composant logiciel issu de la conception générale:

• Description du module, paquetage ou de la classe (en fonction du paradigme utilisé et de la granularité visée). Pour chaque élément :
  • Rappel des objectifs du composant (rappel des besoins liés)
  • Lister les composants utilisés par ce composant et ceux utilisant ce composant
    • Définir les différentes interfaces et leurs visibilités
  • Lister les classes/les structures de données/les méthodes/les fonctions du composant. Pour chacune:
    • Explication de son rôle
    • Définir le type de tous les attributs/variables la composant
    • Préciser l'algorithme utilisé pour chaque méthode/fonction

La lecture de ce document doit permettre à un développeur de n'avoir qu'à traduire en langage de programmation chaque élément présenté sans avoir à se référer à d'autres documents techniques (exception faite du plan de tests).

Le niveau de détail attendu doit lui permettre de réaliser cette traduction sans aucune difficulté. Chaque élément présenté correspond à un besoin exprimé dans le cahier des charges et à un point qui sera vérifié et validé dans le cahier de recette.

Modèle de document : A venir

Le manuel d’utilisation est un document décrivant l’ensemble des fonctionnalités de votre application ainsi que les actions à réaliser afin de la mettre en œuvre. Le manuel d’utilisation doit permet à l’utilisateur final d’exploiter ses fonctionnalités. Les rubriques du manuel d’utilisation sont les suivantes :

1. Mise en œuvre : Indique la manière d’utiliser l’application pour réaliser les tâches de base
2. Liste des commandes : Décrit l’ensemble des commandes de l’application
3. Messages d’erreur : Décrit les erreurs pouvant sur venir et les procédures permettant leur résolution

Modèle de document : Modèle de manuel d'utilisation

Le manuel d’installation est un document rassemblant l’ensemble des procédures nécessaires à la mise en place de votre application dans son environnement de production (conditions réelles d’utilisation). Le manuel d’installation permet à un administrateur système d’installer et de configurer l’application sur des systèmes informatiques. Les rubriques du manuel d’installation sont les suivantes :

1. Installation du matériel (préciser le matériel à installer et les opérations nécessaires à sa mise en fonction)
2. Paramétrage du système (lister les opérations nécessaires pour paramétrer convenablement le système)
3. Installation du logiciel (lister les opérations nécessaires pour installer le logiciel : copie de fichiers, etc.
4. Paramétrage du logiciel (lister les opérations nécessaires pour paramétrer convenablement le logiciel)
5. Installation des données (lister les opérations nécessaires à la mise en place des données de l’application : copie de fichiers, création de base de données, etc.)
6. Autres informations (lister d’autres opérations utiles : informer les utilisateurs, mettre hors service une application le temps de l’installation, procédure de mise à jour, etc.)

Modèle de document : Modèle de manuel d'installation

Il vous est demandé de fournir une documentation interne de votre application. Cette documentation vise à faciliter la maintenance de votre application par un tiers. Celle-ci peut prendre plusieurs formes en fonction du langage utilisé pour l’implantation, e.g., javadoc pour java, Doxygen pour C++.
Toutefois, un document généré automatiquement à l'aide de ces outils est insuffisant.

Elle doit aussi contenir une description issue de l'analyse détaillée du projet :

• Description des modules ou des classes. Pour chaque module :
  1. Rappel des objectifs du module
  2. Relations d’utilisation avec d’autres modules
  3. Lister les modules utilisés par ce module et ceux utilisant ce module
  4. Définitions de types : Lister les définitions de type ou les attributs de l’objet associé au module
  5. Procédures externes : Lister les procédures visibles par les modules utilisant ce module
  6. Variables externes : Lister les variables visibles par les modules utilisant ce module

Le plan de tests est très important dans la mesure où il garantit que votre logiciel respecte le cahier des charges. Les rubriques suivantes doivent être présentes:

1. Présenter un ensemble de tests ou recettes ainsi que leur ordonnancement
2. Description des tests d’intégration. Pour chaque test :
   1. Description du test : Décrire le test de façon externe
   2. But du test :Décrire ce que prouve le test
   3. Principe de réalisation : Décrire la procédure de test ainsi que les paramètres et
3. Description des tests unitaires : Pour chaque module/classe :
   1. Mise en œuvre
   2. Pour chaque jeu d’essai : Données d’entrées, résultats attendues, critère d’évaluation

• Les tests fonctionnels du plan de test sont-ils les mêmes que ceux du cahier de recette ?
  En fait, il ne s'agit pas tout à fait de la même chose, et on s'attend à ce que les tests fonctionnels du plan de test soient au moins aussi nombreux que les tests qui figurent dans le cahier de recette.
  En effet, le cahier de recette permet de vérifier que le fonctionnement de l'application correspond de manière satisfaisante à ce qui est attendu par la maitrise d'ouvrage (le “client”) afin de permettre sa validation. L'ensemble des tests qu'il contient doit donc être compris comme un minimum.
  Tandis que les tests décrits dans le plan de test doivent couvrir l'ensemble des fonctionnalités de l'application conçue. Il est raisonnable de considérer qu'au cours de la conception de l'application, la maîtrise d'oeuvre ait pris en considération des situations ou des contraintes qui n'avaient pas été envisagées lors de l'élaboration du cahier des charges, ni lors de l'élaboration du cahier de recette. Il est évidemment indispensable que le plan de test en tienne compte. Il en est de même lorsque le périmètre fonctionnel de l'application s'avère être plus vaste que celui qui a été défini dans le cahier des charges.

Modèle de document : Modèle de plan de test

Le rapport du projet est un document qui peut contenir toutes les informations ne figurant pas dans les autres documents demandés.

Sur le wiki de la forge, vous devez:

• mettre les photos des membres du groupe
• le résumé en français
• le résumé en anglais

Vous devez déposer sur la forge votre diaporama de soutenance et une version sonorisée de ce diaporama. Cette version correspond à l'enregistrement de votre exposé; elle peut être réalisée lors de vos présoutenances par tous les membres du groupe ou par un seul membre du groupe lors de votre préparation.

Pour savoir quels outils utiliser, consulter la FAQ: Quel logiciel utiliser pour effectuer des captures video ?