lundi 14 mars 2011

Rédaction d'un rapport de stage

Mise à jour le 23 mars 2011
Ce document doit encore être modifié notamment pour indiquer les livrables attendues à chaque étape du déroulement d'un projet.

A l'attention de mes étudiants, une compilation de conseils que j'ai glanés ces dernières années (merci à mes collègues).

Conseils de rédaction
  • Faites des phrases courtes ou des listes plutôt que des longues phrases.
  • Pour chaque phrase ou paragraphe, réfléchissez à l'effet que vous voulez produire sur le lecteur. Mettez vous à sa place et demandez vous si ce que vous avez écrit lui permet de comprendre le message que vous souhaitez lui faire passer.
  • Faites suivre systématiquement la première apparition d'un terme spécifique à votre domaine d'une définition et d'un exemple illustrant ce qui tombe sous votre définition et ce qui n'est pas couvert par votre définition
  • Expliquez toujours un acronyme lors de sa première occurrence
  • Des schémas sont toujours bon car ils permettent souvent de comprendre plus rapidement.
  • Pensez à faire des schémas assez légers. Les gros schémas peuvent toujours être simplifiés en regroupant des parties qui sont explicitées/détaillées ailleurs.
  • Vous pouvez être amené à décrire le travail réalisé par quelqu'un d'autre que vous. Il faut que cela soit clairement dit. Vous avez le droit de faire des citations et le devoir de citer les sources dans une bibliographie en fin de votre document.
  • La compréhension de votre rapport principal ne doit pas nécessiter de se reporter constamment aux annexes.
  • N'hésitez pas à mettre quelques notes de bas de page. Ceux-ci ne doivent pas contenir des informations nécessaires à la compréhension seulement des complémentaires.
  • Chaque figure doit avoir un titre (éventuellement une légende explicative), un numéro, et être référencée dans le texte. Une figure non citée par la suite fait perdre la piste de lecture.
  • Préférez une numérotation des titres avec des chiffres plutôt que farfelue qui mélange lettres, chiffres et numération romaine
  • Ayez un style sobre, aéré et consistant (choisissez vous une norme dès le départ, par exemple : ligne de code en "Courier New" ou "DejaVu sans mono" taille 10 aligné à gauche, texte normal en "arial" taille 10 ou 11 justifié, etc.).
  • Numérotez vos pages.
  • en tête et pied de page bien venu avec nom du projet (éventuellement abrégé) et noms des étudiants
  • Pensez à faire une table des matières (éventuellement deux : une sommaire au début et complète à la fin)
  • Faites un glossaire si nécessaire
  • Ne recopiez pas introduction, résumé en français et en anglais, présentation de l'entreprise, conclusion d'anciens rapports de stage. Le plus souvent, ce sont de très mauvais textes qui sont recopiés !
  • N'écrivez pas des choses que vous ne comprenez pas.
Contenu d'un rapport
Pour mes étudiants en DUT 2eme année, 30 pages environ.

Page de garde
  • titre de votre projet
  • date de réalisation (éventuellement numéro de version)
  • noms des étudiants et leur groupe
  • nom de l'encadrant
  • logo des entités encadrantes ou commanditaires
Introduction 
Globalement 1 page avec un paragraphe par item.

  • contexte du projet
  • présentation du sujet qui doit être compréhensible pour quelqu'un qui n'est pas du domaine
  • annonce du plan du rapport
Environnement
1-2 pages
  • Situation de l'établissement où vous avez fait votre stage, au sein de l'entreprise
  • Fonctionnalités de cet établissement (production, administration, etc.)
  • Situation du service où vous avez fait votre stage, au sein de l'établissement de l'entreprise où vous avez fait votre stage
  • Environnement matériel et logiciel dans lequel vous avez travaillé
Expression du besoin
Autour de 5 pages (essentiellement sur le détail de l'expression du besoin)
  • Contexte détaillé : problèmes ayant amenés le client à proposer ce sujet, enjeux qui pourraient être solutionnés par votre travail
  • Présentation de l'existant et de ses limites
  • Situation de ce que vous avez réalisé au sein des applications existantes dans la solution utilisée auparavant par l'entreprise
  • Brève description de ce qui vous a été fourni : documents ? ressources logicielles ? 
  • L'expression des besoins qui vous a été fournie. Si celle-ci vous a été donnée sous forme écrite, la fournir entre guillemets. 
  • L'environnement matériel et logiciel que vous deviez utiliser
Spécification (documents d'analyse)
10-12 pages

  • Choix d'orientation : ce que vous avez décidé de faire/ne pas faire dans le projet, et la justification (faisabilité, temps, coût, complexité,...)
  • Couche/package de votre architecture en dissociant les aspects métiers, IHM et interaction avec la base de donnée
  • Modèle des données 
  • Modèle des objets : 
    • 1 ou + diagrammes de classe (découpage en package). Les attributs et rôles en français, les invariants en français. Si certaines relations d'héritage nécessitent des commentaires, vous pouvez les insérer dans le document
  • Prototypage de l'interface homme machine
  • Cas d'utilisation : 1 ou + diagrammes de cas d'utilisation
  • Scénarios d'utilisation : diagrammes de séquence (scénario normal, avec alternatives et avec erreurs). Tests d'acceptation (suite d'opérations et résultats attendus dans une situation donnée)
  • Diagramme d'états pour modéliser le comportement de chaque algo important
Conception
5-7 pages

  • Choix d'implantation : 
    • comment se traduit la spécification formelle en terme de langage objet ; pour chaque élément de l'analyse (classe, opération, relations), décrivez comment il sera réalisé (attribut de classe, méthode d'objet, méthode statique, instance de classe existante, nouvelle classe, etc.)
      • chaque classe de l'analyse doit être identifiée avec soit une nouvelle classe, soit une classe existante
      • chaque opération doit être associée à une classe pour en faire une méthode
    • de même pour la mise en oeuvre au niveau de la base de donnée
    • et de la conception de l'IHM
  • Structure de fichiers du projet, les fichiers les plus importants
  • Diagrammes d'interaction : pour chaque cas d'utilisation, donner 1 ou + diagrammes de séquence en utilisant les classes et méthodes définies dans les choix d'implantation.
  • Description des opérations : pour chaque méthode critique, décrire son fonctionnement en pseudo-code ou en utilisant une machine à états.
  • Description des cycles de vie : pour chaque classe qui le nécessite (dès l'instant que le cycle de vie n'est pas trivial), décrire le cycle de vie de ses objets par une machine à états.
  • Tests unitaires : pour chaque classe, donner un jeu de test unitaire et de tests d'intégration. Préciser aussi l'ordre d'intégration des classes

Test de votre logiciel
0-4 pages

  • Test boîte blanche vs test boîte noire, stratégie de test. Comment ont été constitués les jeux de test. Qui les a constitué ? Résultat des tests.
  • Tests unitaires : trace d'exécution (ne doivent apparaître que les erreurs) + commentaires
  • Tests de scénarios de l'analyse : mise à jour et complément éventuels des scénarios + résultats des tests + commentaires
  • Synthèse : analyse de l'ensemble des tests, comparaison des résultats avec ce qui était prévu dans l'analyse et la conception


Démarche que vous avez suivie
2-4 pages
  • La démarche de travail que vous avez suivi entre vous et avec votre encadrant
  • Répartition formelle : qui est sensé faire quoi dans le groupe de projet, description précise du découpage des tâches pour la phase en cours
  • Répartition effective : qui a fait quoi et quand (soit de manière hebdomadaire soit en découpant en 4 périodes : "avant le début officiel du projet en janvier au retour des vacances de noël", "depuis début Janvier et avant la semaine dédiée au projet et les vacances d'Hiver", "durant la semaine de projet", "après la semaine de projet et avant le rendu du rapport" . Si vous travaillez séparément, désignez un coordinateur.
  • Compte rendu sur l'activité d'analyse, de conception, de codage et de test
    • notamment les difficultés rencontrées : problèmes qui vous ont particulièrement gêné pendant l'analyse, la conception, la réalisation et les tests, autres
  • Compte rendu sur le travail général

Conclusion
1 à 3 pages

  • bilan de ce qui a été réalisé en regard de l'existant et de ce qui était attendu
  • perspectives pour poursuivre
Annexes
  • Eventuellement le cahier des charges
  • Manuel Utilisateur
    • Description des procédures pour réaliser 
      • l'installation,
      • la configuration
      • et l'utilisation de l'application 
        • les aspects généraux de(s) l'interface(s) ou bien intégration des copies d'écran
        • les différentes opérations disponibles dans l'application et comment les exécuter
    • Description des problèmes courants
    • Mini foire aux questions
    • Paquetage des fichiers sources


Livrables
une archive contenant

  • les sources du code src, 
  • javadoc (documentez avec la syntaxe JAVADOC chaque classe, attribut, méthode ou exception. Générez la doc HTML et empaquetez le tout (doc + classes squelettes))
  • doc/userGuide (binaire et source)
  • doc/rapport (binaire et source)
tar zcf -`date +%Y%m%d`-`date +%H%M`.tgz projet/  

3 commentaires: