EPITECH

INNOVATIVE PROJECT

BILAN DOCUMENTAIRE 3
CONSIGNES POUR LE BILAN DOCUMENTAIRE DE
DECEMBRE

PROMO 2018
 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

Description du document
Titre Bilan documentaire 3
Objet Consignes pour le bilan documentaire de décembre
Auteur Matthieu Bargheon
Responsable Flavien Astraud
E-mail [email protected]
Mots-clés Documentation, utilisateur, technique, installation, prérequis
Promotion 2018
Date de mise à jour 15 novembre 2017
Version du modèle 1.0

Tableau des révisions
Date Version Auteur Section(s) Commentaires
14/11/2017 1.0 Matthieu Bargheon Toutes Première version

PAGE 2 SUR 12
 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

Table des matières

1. Objectifs du bilan ........................................................................................................................ 4
1.1. Description ....................................................................................................................................... 4
1.1.1. Documentation utilisateur ....................................................................................................... 4
1.1.2. Documentation technique ....................................................................................................... 4
1.1.3. Liste des prérequis ................................................................................................................... 4
1.1.4. Documentation d’installation .................................................................................................. 5
1.2. Glossaire ........................................................................................................................................... 5
2. Formalités ................................................................................................................................... 6
3. Description des documents ........................................................................................................ 7
3.1. Formalisme ....................................................................................................................................... 7
3.2. Contenu du document ..................................................................................................................... 7
3.2.1. Résumé .................................................................................................................................... 7
3.2.2. Documentation utilisateur ....................................................................................................... 8
3.2.3. Documentation technique ....................................................................................................... 8
3.2.4. Liste des prérequis ................................................................................................................... 9
3.2.5. Documentation d’installation ................................................................................................ 10
4. Points évalués ........................................................................................................................... 11
5. Remarques ................................................................................................................................ 12

PAGE 3 SUR 12
 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

1. Objectifs du bilan
1.1. Description
Ce bilan a pour but de vous faire écrire la troisième version des documentations liées à votre
projet. Les documents accompagnant votre projet sont les documentations utilisateur (manuel
d’utilisation), technique (manuel du développeur), d’installation (procédure d’installation), et la
liste des prérequis pour votre projet (matériels et logiciels).
Un point clé à garder à l’esprit : ces documents, au même titre que votre code, doivent faire
l’objet d’une évolution constante et progressive dans leur rédaction, et non uniquement avant
un bilan.
Comme c’est une troisième version, nous attendons que vous preniez en compte les
commentaires de la correction de la deuxième version. Nous attendons également que vous
fassiez également preuve d’auto critique en cherchant à améliorer ces documents sur les axes qui
n’ont pas été mentionnées dans la correction. La documentation doit également avoir évolué
avec l’avancement de votre projet.

1.1.1. Documentation utilisateur
Le but de la documentation utilisateur (UD) est d'avoir un guide pour que les utilisateurs de votre
projet puissent s'en servir pleinement (le manuel de votre gaufrier pour vulgariser).
La forme de ce document dépend du projet et du type d'utilisateur. Pour les EIP de type jeu vidéo,
le petit livret contenu dans la boîte de jeu est une excellente illustration.

1.1.2. Documentation technique
Le but de la documentation technique (TD) est de maintenir un manuel technique de votre projet
(encore pour vulgariser, la revue technique de votre voiture par exemple). Ce document doit
décrire la conception du projet, son organisation, le moyen de contribuer, sa gestion, ses tests, et
tous les éléments qu’un développeur qui rejoindrait le projet aurait besoin de connaître pour
développer sur le projet. Le but est vraiment d’établir un guide du développeur qui permettrait à
toute personne rejoignant l’équipe de contribuer au projet en comprenant son état, sa structure,
et la façon de contribuer, sans avoir à vous solliciter pour obtenir les informations nécessaires.

1.1.3. Liste des prérequis
Le but de la liste des prérequis (PR) est de bien comprendre quelles sont les configurations
minimales et recommandées dont votre projet a besoin (matériel et logiciel) pour fonctionner.
Cela viendra appuyer les éventuelles demandes matérielles et logicielles que vous pourrez
formuler, et permettre à l’équipe EIP de globaliser vos besoins.

OBJECTIFS DU BILAN PAGE 4 SUR 12

 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

1.1.4. Documentation d’installation

Le but de la documentation d’installation (ID) est de maintenir à jour la procédure pour installer
votre projet (partie serveur et cliente). Ce document doit vous permettre en suivant les étapes
pas-à-pas d’installer votre projet sur un environnement vierge. Ce document mis entre les mains
d’un nouveau contributeur doit lui permettre d’effectuer son installation (pour tous les
composants de la partie serveur et cliente, et pour les environnements de développement
comme de production), et le résultat doit être que votre projet soit fonctionnel et utilisable.

1.2. Glossaire
- F -
FAQ : Foire aux questions (ou frequently asked questions en anglais). C’est une liste de questions
les plus communes qu’un utilisateur peut se poser et auxquels vous apportez une réponse.

- G -
Gestion de configuration : C’est le nom donné aux outils de « versioning » (du code ou
documentaire). Par exemple SVN est un outil de gestion de configuration tout comme GIT, etc.

- U -
UML : (Unified Modeling Language) c’est un langage de modélisation universel qui permet de
représenter logiquement et physiquement des processus et produits d’ingénierie.
http://uml.free.fr est une référence simpliste qui liste les types de diagrammes et leur grammaire.

OBJECTIFS DU BILAN PAGE 5 SUR 12

 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

2. Formalités
Les documents seront corrigés et il n’y aura pas de bilan associé avec un professeur.
Les documents UD, TD, ID devront être au format « PDF », la liste des prérequis dans un fichier
texte UTF8. Ces documents devront être rendus en français pour le dimanche 17 décembre 2017
à 23h42. Ils devront être rendus sur votre SVN dans rendu :
https://labeip.epitech.eu/svn/2018/<groupe>/rendu/

Les documents suivant devront figurer :
• 2018_UD3_<Groupe>.pdf (documentation utilisateur)
• 2018_TD3_<Groupe>.pdf (documentation technique)
• 2018_ID3_<Groupe>.pdf (documentation d’installation)
• 2018_PR3_<Groupe>.txt (liste des prérequis matériels et logiciels)

FORMALITES PAGE 6 SUR 12

 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

3. Description des documents

Comme tous les documents de l’EIP, ces documents doivent présenter un contenu construit,
élaboré, avec plusieurs parties obligatoires.

3.1. Formalisme
Tout d’abord, les documents doivent avoir un format spécifique. Il est obligatoire de voir figurer
des en-têtes et pieds de pages, une page de garde qui indique le titre du document, le nom du
groupe, ainsi qu’un visuel du groupe et de l’EIP/Epitech.
Ensuite, vous devez faire figurer sur la deuxième page un résumé du document (cf Résumé),
optionnel pour la documentation utilisateur (à vous de juger de la pertinence).
Sur la troisième page, vous devez faire figurer un cartouche du document (propriétés,
métadonnées du document), et un tableau des révisions permettant de tracer l’historique de
votre document à la façon d’un SVN (date, version, auteur, sections modifiées, commentaires).
Enfin sur la quatrième page doit figurer un sommaire à jour, directement généré depuis le
contenu de votre document, tenant sur une page si possible (en réduisant la profondeur utilisée
par exemple).
Votre texte doit être justifié, et vos pages doivent être numérotées.

3.2. Contenu du document
3.2.1. Résumé
Le résumé est un paragraphe (généralement de 200 à 300 mots, mais cela dépend de la taille du
document) que le lecteur trouvera au début du document. Ce paragraphe sert à synthétiser les
informations importantes du document, ainsi que les arguments principaux. On trouvera aussi les
résultats et la conclusion du document.
Le résumé sert aux lecteurs qui souhaitent prendre rapidement connaissance du contenu du
document :
• Il pourra décider si l'article l'intéresse au non ;
• Il pourra aller directement à la section qui l'intéresse.

Le résumé doit être bref et précis. Utilisez des phrases courtes et évitez les énumérations et
graphiques.
Le résumé doit contenir :
• Le contexte de départ du document ;
• Les idées principales (les choix et arguments) ;
• La conclusion.

Il ne s’agit donc pas d’un texte présentant la structure du document (introduction), mais bien d’un
texte présentant des éléments de contenu (résumé).

DESCRIPTION DES DOCUMENTS PAGE 7 SUR 12

 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

3.2.2. Documentation utilisateur

Vous devez fournir une version mise à jour de la documentation utilisateur. Celle-ci doit
correspondre à un manuel utilisateur, elle doit permettre à un utilisateur de votre projet
d’installer la partie cliente si c’est nécessaire et de prendre en main votre projet avec toutes ses
fonctionnalités. Elle doit être claire et orientée non technique, tel qu’un manuel de n’importe
quel appareil que vous utilisez chez vous.
Pour les EIP jeu vidéo, il est fortement recommandé de faire une documentation utilisateur type
livret de jeu qui est beaucoup plus adaptée, comme évoqué précédemment.
Elle peut contenir par exemple les points suivants (mais non exhaustif et non applicable à tous les
projets) :
• Un schéma fonctionnel très haut niveau (commercial) de votre projet ;
• Installation et désinstallation pas à pas des parties clientes (s’il y en a) ;
• Liste des fonctionnalités triées et organisées par thème. Il faudra appuyer avec des
captures d’écran ainsi qu’une numérotation de chaque zone d’interaction pour les
référencer et les décrire ;
• Pour les applications mobiles, une capture de chaque OS mobile est mieux car il y a des
différences, mais ne répétez pas 3 fois la description fonctionnelle (à priori seule
l’interface peut changer un peu) ;
• Une FAQ ;
• Lien vers le site vitrine et/ou d’autres documentations.

Ce document est destiné aux utilisateurs : il doit être clair et léger, agrémenté de captures
d'écran, agréable à lire. Il doit être adapté à votre cible.

3.2.3. Documentation technique
Ce document est un « guide du développeur » qui doit permettre à un nouvel intervenant
technique de comprendre les différentes parties, l’organisation de l’architecture du projet, les
différents modules et comment contribuer sur ces derniers.
Il doit permettre à un développeur de comprendre les règles et conventions utilisées pour le
développement et les appliquer à des nouveaux modules en développement.
La documentation peut contenir les thèmes suivants (mais non exhaustif et non applicable à
tous) :
• Vulgarisation de la vue du projet via un schéma de haut niveau expliquant le
fonctionnement ;
• Vue logique de tous les composants et modules en place dans la solution (diagramme de
composants) ;
• Utilisation du système de gestion de configuration, stratégie, et règles ;
• Découpage en grands blocs avec explication de l’implémentation des grands composants
via des diagrammes de séquence, de composants, objets ;

DESCRIPTION DES DOCUMENTS PAGE 8 SUR 12

 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

• Description des API et interfaces (lien vers de la documentation générée [publiquement

accessible ou avec les identifiants fournis] et compléments d’explication, mais pas de
duplication d’information par rapport à la documentation générée) ;
• Norme du code ;
• Tests et conditions de passage de l’environnement de développement à une release ;
• Stratégie de release ;
• Release note.
Si vous avez prévu une documentation du code générée via un outil ou autre, un lien dans la
documentation technique vers lequel la documentation du code est disponible suffit pour la
description de ces API, et interfaces. Cela ne vous dédouane cependant pas des diagrammes et
autres modélisations ainsi que des explications. Dans ce cas, il vous suffit de faire référence à
votre documentation de code, et si nécessaire, d’ajouter des éléments. Il serait mieux d’avoir une
description détaillée dans la documentation du code et des exemples de « code snippet » ou
autre.
Ce document est une architecture détaillée de ce que vous faites et un « guide du développeur ».
Ce document doit contenir la liste des bugs techniques connus et un historique des « release note
», « patch note » ou encore « change log » qui permet de retracer l'évolution des bugs et leur
correction. Vous pouvez (et il est même conseillé de le faire) mettre cela en relation avec un
système de gestion de tickets (bug tracking, assignement de tâches comme GIT, TFS ou autre).
Ce document doit permettre à un nouveau contributeur d’être autonome sur le projet. Il doit
donc y trouver toutes les informations nécessaires.

3.2.4. Liste des prérequis
Ce fichier texte UTF8 doit lister les prérequis matériels et logiciels. Ceux-ci doivent permettre de
définir le matériel et logiciel nécessaires à votre configuration minimum pour pouvoir installer et
utiliser votre projet sur les parties clientes et serveur. Veillez à bien séparer dans votre fichier les
prérequis matériels des prérequis logiciels.
Les prérequis matériels peuvent contenir par exemple :
• Nombre de CPU ;
• Quantité de mémoire vive ;
• Taille et vitesse d’accès des disques durs ;
• Architecture spécifique.
Les prérequis logiciels peuvent contenir par exemple :
• Version du système d’exploitation ;
• Librairies et leurs versions ;
• Outils et frameworks.

DESCRIPTION DES DOCUMENTS PAGE 9 SUR 12

 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

3.2.5. Documentation d’installation

Cette documentation doit ressembler à une procédure d’installation étape par étape, et a pour
but de permettre à n’importe qui d’installer votre projet (parties serveur(s) et clientes), et de le
rendre fonctionnel depuis un environnement vierge.
Ce document peut contenir par exemple :
• Liste des technologies utilisées et leur référence (vous pouvez faire référence aux
prérequis) ;
• Configuration et installation des environnements de développement et/ou de recette
(partie serveur) ;
• Configuration et installation des environnements de production (partie serveur) ;
• Configuration et installation des parties clientes ;
• Configuration et installation des outils de développement ;
• Procédure pas-à-pas d’installation ;
• Commandes à exécuter à copier/coller (exemple guide d’installation Gentoo).

DESCRIPTION DES DOCUMENTS PAGE 10 SUR 12

 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

4. Points évalués
Les différents éléments sur lesquels se basera la notation sont :
• Le format du document :
o Présence et qualité de la page de garde ;
o Présence et qualité du cartouche et du tableau des révisions ;
o Présence et qualité des en-têtes et pieds de page ;
o Mise en forme générale du document ;
o Qualité de l’écrit (français) ;
• Contenu de la documentation utilisateur (UD) :
o Informations concernant l’accès au projet (téléchargement et installation par
exemple) ;
o Guide d’utilisation détaillé ;
o Informations et contact utiles ;
• Contenu de la documentation technique (TD) :
o Vue globale du projet et de son architecture ;
o Accès aux sources ainsi qu’aux éventuels outils tiers et API ;
o Présentation technique détaillée de chaque partie ;
o Norme du code ;
o Tests et stratégie de release ;
• Contenu de la documentation d’installation (ID) :
o Accès aux éléments nécessaires au déploiement du projet ;
o Procédure d’installation des parties serveur (développement ou recette,
production) ;
o Procédure d’installation des parties clientes ;
o Procédure d’installation des environnements de développement (poste de travail
du développeur) ;
• Contenu de la liste des prérequis (PR) :
o Présence et exhaustivité des prérequis logiciels ;
o Présence et exhaustivité des prérequis matériels.

POINTS EVALUES PAGE 11 SUR 12

 EPITECH INNOVATIVE PROJECT - BILAN DOCUMENTAIRE 3

5. Remarques
Pour nous contacter :
• Ouvrir un ticket sur l’intranet : https://eip.epitech.eu/#/tickets
• Sujet : [2018][Groupe][DA3] <Objet de votre ticket>
• Mots clés : DA3
Toutes les demandes par e-mail ou ne respectant pas ce formalisme de tickets seront clôturées
sans réponse.

REMARQUES PAGE 12 SUR 12