Documenta*on du logiciel Document distribué sous licence CC by-nc-nd :
http://creativecommons.org/licenses/by-nc-nd/2.0/fr/
Véronique Baudin E-‐mail: [email protected]
La Londe Les Maures – Décembre 2011
Deux cas de figure
• Documenter un logiciel depuis sa concep*on
• Documenter un logiciel existant peu ou pas documenté – Comprendre pour documenter
– Quels documents produire
09/12/2011 2 Documenta*on de logiciel
Participer à un projet
Utilisateurs
Maître d'ouvrage Maître d'oeuvre
Exploitation informatique
Chef de projet
Equipe projet
- Définir le besoin métier - Définir/Fournir des tests
- Utiliser le logiciel
- Assurer la bonne restitution des besoins, de leur spécification détaillée - Définir des tests fonctionnels
- Assurer la responsabilité de la conception, de la réalisation technique et de l'intégration du système
- Fournir l'infrastructure matérielle et logicielle - Assister les utilisateurs
- Garantir les délais du planning - Assurer le suivi du projet - Coordonner les différents acteurs - Veiller à la qualité des logiciels produits - Comprendre le
besoin exprimé - Produire un logiciel de qualité
8/12/2011 PEPI-IDL 3
PROJET INFORMATIQUE: les rôles
09/12/2011 Documenta*on de logiciel 4
OUTILS PROJETS : Analyse Fonc7onnelle Rémi Bachelet – Ecole Centrale de Lille – mai 2011
Documenta*on: pourquoi faire ?
• Pour garan*r un accès rapide et fiable aux informa*ons u*les à toute personne impliquée dans le projet
• Pour faciliter le partage de l’informa*on • Pour favoriser une mise à jour rapide et facile • Pour garan*r la cohérence des informa*ons • Pour faciliter la réu*lisa*on de codes • Pour archiver dans un but historique ou sta*s*que
09/12/2011 Documenta*on de logiciel 5
Périmètre de couverture de la documenta*on
• Documenta*on du logiciel – Spécifica*on – Codes source, procédure d’installa*on ou de généra*on
– Manuels (u*lisateur, administrateur, développeur/mainteneur)
• Documenta*on du projet – Plannings de réalisa*on – Rôles et responsabilités – Ges*on de projet
09/12/2011 Documenta*on de logiciel 6
Périmètre de couverture de la documenta*on
• FDocumenta=on du logiciel – Spécifica*on – Codes source, procédure d’installa*on ou de généra*on
– Documenta*on (u*lisateur, administrateur, développeur/mainteneur)
• Documenta*on du projet – Plannings de réalisa*on – Rôles et responsabilités – Ges*on de projet
09/12/2011 Documenta*on de logiciel 7
Périmètre de couverture de la documenta*on
• FDocumenta=on du logiciel – Spécifica*on – Codes source, procédure d’installa*on ou de généra*on
– Documenta*on (u*lisateur, administrateur, développeur/mainteneur)
• Documenta*on du projet – Plannings de réalisa*on – Rôles et responsabilités – Ges*on de projet
09/12/2011 Documenta*on de logiciel 8
M Nécessaire cohérence entre les 2 types de documenta*on
Documenta*on du logiciel • Expression des besoins
– défini*on de ce que l’on a_end, le périmètre, une « prioré*sa*on » des fonc*ons.
– se construit par un dialogue entre le « demandeur » et celui/ceux qui vont exécuter/réaliser la demande
– Besoins = bases sur lesquelles le projet va être établi (trace écrite impéra*ve). • Architecture/Concep=on
– Vue d’ensemble – Rela*ons avec l’environnement et les principes u*lisés dans la concep*on et
l’implémenta*on des composants logiciels • Documenta=on technique ou détaillée
– Documenta*on du code (algorithmes, interfaces, API, tests) • Manuels
– U*lisateurs finaux, administrateurs système, support • Valorisa=on/Diffusion
– Faire connaître, diffuser un logiciel (associer une licence de diffusion)
09/12/2011 9 Documenta*on de logiciel
PLAN 1. La documenta=on pour un nouveau logiciel
a) Expression des besoins ou Analyse fonc=onnelle b) Architecture/Concep=on c) Documenta=on technique ou détaillée d) Manuels e) Valorisa=on/Diffusion f) Aspects pra=ques de mise en oeuvre g) Quels documents produire en lien avec le contexte de développement
et d’u=lisa=on ? 2. La documenta=on pour un logiciel existant
a) Pré-‐requis b) Comprendre le fonc=onnement c) Manuels à produire/compléter
3. Mise en œuvre: analyse et proposi=ons
09/12/2011 Documenta*on de logiciel 10
Expression des besoins … • Objec*fs
– Définir le contexte général (mé*er, technique, juridique, ...) dans lequel le projet va être réalisé.
– Définir les acteurs (humains et non humains) qui vont interagir avec le système.
– Définir les fonc*onnalités a_endues du système. – Définir le contexte technique du projet (serveurs, réseau, etc...) – Définir le fonc*onnement dynamique de chaque fonc*onnalité. – Définir les besoins en interface homme machine (IHM). – Rédiger un cahier des charges fonc*onnel et technique qui perme_ra de réaliser le projet et de le valider au fur et à mesure jusqu'à la phase de rece_e finale (défini*on des tests).
09/12/2011 11 Documenta*on de logiciel
Expression des besoins …
• Comment a_eindre les objec*fs ? – Essen*ellement par le dialogue avec le/les maître(s) d’ouvrage, les u*lisateurs finaux
– Comment obtenir les informa*ons ? • Méthode APTE • Diagramme PERT • …..
• Exemple: ges*on des supports vidéos de la maison
09/12/2011 Documenta*on de logiciel 12
Contexte du problème à traiter
09/12/2011 Documenta*on de logiciel 13
But à a_eindre
09/12/2011 Documenta*on de logiciel 14
Les 101 dalma=ens Dessin animé de Wolfgang Reitherman, Hamilton Luske et Clyde Geronimi. Sor* en 1961. h_p://www.journaldemickey.com/Dico-‐Disney/Toutes-‐les-‐fiches/D/Les-‐101-‐dalma*ens
But à a_eindre
09/12/2011 Documenta*on de logiciel 15
Fonc*onnalités a_endues: -‐ Localiser un film -‐ Lister les films d’un réalisateur -‐ Lister les films d’un acteur -‐ Lister les films du genre « aventure »
-‐ Gérer les droits parentaux sur un film
-‐ ………
Les 101 dalma=ens Dessin animé de Wolfgang Reitherman, Hamilton Luske et Clyde Geronimi. Sor* en 1961. h_p://www.journaldemickey.com/Dico-‐Disney/Toutes-‐les-‐fiches/D/Les-‐101-‐dalma*ens
Obtenir des informa*ons pour préciser les besoins
• Méthode APTE (Applica*on aux Techniques d’Entreprises): « brainstorming organisé »
h_p://www.techno-‐science.net/?onglet=glossaire&defini*on=10849 h_p://www.methode-‐apte.com/
– À par*r d’un besoin (flou ?) exprimé par l’u*lisateur final, évaluer les contraintes (techniques, économiques, culturelles, ...) qui doivent être plus ou moins prises en compte
– 2 ou*ls graphiques à retenir: • « bête à cornes » pour préciser le(s) besoin(s) • « Pieuvre » pour tenir compte de l’environnement
09/12/2011 Documenta*on de logiciel 16
« Bête à cornes » • Principe
D’après: h_p://commons.wikimedia.org/wiki/File%3ABetecorne.png Par BiMiT (Travail personnel) [Public domain], via Wikimedia Commons
09/12/2011 Documenta*on de logiciel 17
Utilisateur Données
Logiciel
Fonction d’usage ou besoin
À qui doit-‐il rendre service ? Sur quoi va-‐t-‐il travailler ?
Dans quel but ?
« Bête à cornes » • Principe
D’après: h_p://commons.wikimedia.org/wiki/File%3ABetecorne.png Par BiMiT (Travail personnel) [Public domain], via Wikimedia Commons
09/12/2011 Documenta*on de logiciel 18
Utilisateur Données
Logiciel
Fonction d’usage ou besoin
À qui doit-‐il rendre service ? Sur quoi va-‐t-‐il travailler ?
Dans quel but ?
• Applica*on à notre exemple – Logiciel = ges*onnaire de supports vidéo
– U*lisateur = membre de la famille
– Données = DVD, blu-‐ray – But = localiser un film
Pieuvre ou diagramme d’interac*ons
• Objec*f = recenser les fonc*ons de service • Composants = logiciel + éléments de l’environnement
• Fonc*ons ou liens d’interac*on = – Fonc*ons principales (demandes ini*ales de l’u*lisateur) : représentées par un lien entre 2 éléments de l’environnement et passant par « logiciel »
– Fonc*ons contraintes (imposées par un élément extérieur) : représentées par un lien entre « logiciel » et un élément de l’environnement
09/12/2011 Documenta*on de logiciel 19
09/12/2011 Documenta*on de logiciel 20
Ges=onnaire de films
U=lisateur
Armoire de rangement
Films
Fournisseur non
commercial
Magasin de vente
Législa=on sur les droits d’auteurs
Règles de vie de la maison
FP1: Perme_re à l’u*lisateur de sélec*onner un film FP2 : Localiser un film dans l’armoire FC1: Respecter la législa*on (pas de copies pirates) FC2: Respecter les « règles » de la maison (heures limites, choix en fonc*on de l’âge, ….) FC3: Déclarer tout nouveau film acquis FC4: Iden*fier un fournisseur non commercial …..
FP1 FP2
FC1
FC2 FC3
FC4
Expression des besoins • Ou*ls de mise en œuvre
– Langage naturel – Pseudo code du type PDL (Program Design Language) – Diagrammes de flots de données (DFD: Design Flow Datagrams) – Machines à états finis: Réseaux de Pétri, Statecharts, … – Spécifica*ons formelles: B, Z, VDM – UML
• Diagrammes Use Case: iden*fient les acteurs et les fonc*ons principales (cas d’u*lisa*on) • Diagramme de séquence: présente les messages échangés chronologiquement entre les acteurs, les modules, … • Diagramme de déploiement: décrit la disposi*on « physique » des ressources matérielles qui composent le système, et la
répar**on des composants sur ces ressources • Diagrammes d’état: spécifient le comportement d’un composant en réac*on à des évènements • Diagrammes d’ac*vités : précisent les traitements pour (tous) les éléments du système
• Normes et standards de contenu et de rédac*on – IEEE 830 (1998):
• h_p://standards.ieee.org/findstds/standard/830-‐1998.html • h_p://trempet.uqam.ca/Enseignement/Cours/inf5151/Hiver2008/NotesdeCours/PP-‐IEEE%20830-‐%201998.pdf
– NF X50-‐151 Septembre 2007 (AFNOR) • h_p://www.bou*que.afnor.org/NEL5DetailNormeEnLigne.aspx?
&nivCtx=NELZNELZ1A10A101A107&ts=1814127&CLE_ART=FA122246
– NF X50-‐100 Novembre 2011 (AFNOR) • h_p://www.bou*que.afnor.org/NEL5DetailNormeEnLigne.aspx?
&nivCtx=NELZNELZ1A10A101A107&ts=4411344&CLE_ART=FA159967
09/12/2011 21 Documenta*on de logiciel
Document d’architecture/de concep*on
• Objec*fs – Fournir une vue d’ensemble sur le logiciel – Prendre en compte les rela*ons avec l’environnement – Présenter les principes à u*liser dans la concep*on et la réalisa*on des
composants logiciels – Suggérer des approches alterna*ves pour la concep*on et la réalisa*on
• Ou*ls – Modèles d'analyse et d'architecture centrées sur les données : Pressman
R. S., So�ware Engineering: A Prac**oner's Approach, Fi�h Edi*on. McGraw-‐Hill (2001)
– Modèle d'architecture de Philippe Kruchten (4 + 1 vues) : Muller P-‐A, Gaertner N., Modélisa*on objet avec UML, 2em édi*on. Eyrolles (2003)
• Lien u*le – h_p://fr.wikipedia.org/wiki/Architecture_logicielle
09/12/2011 Documenta*on de logiciel 22
Documenta*on technique ou détaillée
• Objec*fs – Définir, expliquer les interfaces de programma*on, les structures de
données, les algorithmes mis en œuvre – Perme_re à un programmeur (non auteur ini*al) de comprendre le
code ou d’intervenir dans ce code
• Ou*ls pour extraire les commentaires du code et générer la documenta*on – Javadoc h_p://www.oracle.com/technetwork/java/javase/documenta*on/index-‐jsp-‐135444.html – Doxygen: h_p://www.doxygen.org/
09/12/2011 Documenta*on de logiciel 23
Documenta*on u*lisateur
• Cible = u*lisateur final – Mode d’emploi du logiciel ou tutoriel – Propose un résumé des fonc*onnalités u*lisables – Précise les limites d’u*lisa*on
• Cible = administrateur – Procédure d’installa*on et de ges*on du logiciel – Précise les pré-‐requis pour un bon fonc*onnement
• Cible = support – Manuel « u*lisateur final » – Plan de tests
09/12/2011 Documenta*on de logiciel 24
Documenta*on marke*ng vs valorisa*on et diffusion
• Posters de présenta*on , ar*cles et autres documents de communica*on
• Fiche PLUME/Développement ESR • Licence de diffusion du logiciel et de sa documenta*on • Site web du logiciel:
– Téléchargement – Contact – Documenta*on – Descrip*on équipe de dev – Informa*on de licence – Mailing list – …..
09/12/2011 Documenta*on de logiciel 25
Aspects pra*ques de mise en œuvre … • La mise en œuvre des différents documents doit être simple et informa*ve • Aucun document n’est figé tant que le projet n’est pas clos • Pas d’informa*ons dupliquées dans différents documents • Pas de mélange d’informa*ons (documenta*on technique/manuel u*lisateur,
expression des besoins/documenta*on technique, ...) • Donner des *tres significa*fs aux documents • Pour chaque document:
– Informa*ons sur le document • Titre • Nom du rédacteur • Date de créa*on du document • Date de dernière modifica*on • Numéro de version • Licence documenta*on (si applicable) • Des*nataires (nomina*fs ou par catégorie)
– Informa*ons dans le document • Iden*fica*on facile • Structura*on des informa*ons (contenu) • Informa*ons compréhensibles par tous, même après la fin du projet • Concis et clair (facile à lire) • U*lisa*on de modèles (diagrammes UML, ….. connus ou bien explicités dans ce document)
09/12/2011 Documenta*on de logiciel 26
Aspects pra*ques de mise en œuvre …
09/12/2011 Documenta*on de logiciel 27
• Acteurs: – Commanditaire
• Interne (INRA) • Mixte (INRA + partenaires projet locaux ou distribués)
– Analyste • Interne • Mixte
– Développeur • Interne • Externe (sous-‐traitance, CDD, partenaire externe, ….)
– U*lisateur • Final
– Interne – Externe
• Administrateur – Interne – Externe
• Développeur – Interne – Externe
• Valorisa*on – À but interne – À but externe
Aspects pra*ques de mise en œuvre …
09/12/2011 Documenta*on de logiciel 28
Document
produire
auteur relecteur
u=lisateur
Support de document
u*liser
compléter
stocker
gérer les versions
gérer les droits d’accès
relire
Scénarios d’u7lisa7on d’un document
Aspects pra*ques de mise en œuvre …
09/12/2011 Documenta*on de logiciel 29
Scénarios de ges7on d’un document auteur
relecteur
u=lisateur
Document produit
u=lisé
archivé
jeté
classé
Comme fichier unique
modifiable Non modifiable
traçable
Comme page(s) de wiki
visible
Par tous ou des
membres du projet
Par tout public
Par étape du projet
Par auteur(s)
Par règles projet, organisme, …
Généra=on automa=que
Ou=ls de suivis des modifs
PLAN 1. La documenta=on pour un nouveau logiciel
a) Expression des besoins ou Analyse fonc=onnelle b) Architecture/Concep=on c) Documenta=on technique ou détaillée d) Manuels e) Valorisa=on/Diffusion f) Aspects pra=ques de mise en oeuvre g) Quels documents produire en lien avec le contexte de développement
et d’u=lisa=on ? 2. La documenta=on pour un logiciel existant
a) Pré-‐requis b) Comprendre le fonc=onnement c) Manuels à produire/compléter
3. Mise en œuvre: analyse et proposi=ons
09/12/2011 Documenta*on de logiciel 30
La documenta*on pour un logiciel existant
Pré-requis • Pourquoi reprendre un logiciel existant ?
– Pour l’améliorer (ajout ou correction de bogue) – Pour l’intégrer dans un logiciel plus important – Pour permettre à des utilisateurs de s’en servir – Pour s’inspirer des solutions mises en œuvre pour un autre logiciel – …
• Nécessité de disposer de sa licence pour définir les actions légales possibles
• Recueillir tous les documents existants possibles même incomplets • Recueillir les expertises des utilisateurs de ce logiciel • Rechercher un des auteurs initiaux
09/12/2011 Documenta*on de logiciel 31
Comprendre le fonctionnement du logiciel • Par la lecture du code (si possible) • Par de la rétro-ingénierie (si possible)
– http://2011.rmll.info/IMG/pdf/Maintenir_du_code_historique_-_RMLL_2011.pdf – http://fr.wikipedia.org/wiki/Rétro-ingénierie
– Mais attention aux problèmes légaux possibles !! • Par des tests en utilisant l’expertise d’autres
utilisateurs réguliers (s’ils existent) 09/12/2011 Documenta*on de logiciel 32
La documenta*on pour un logiciel existant
Manuels à compléter ou à produire • Documents cibles:
– Documenta*on technique détaillée, en ajoutant si possible des commentaires per*nents dans le code
– Manuels u*lisateur, en enrichissant si nécessaire les jeux de tests pour la cible « support »
09/12/2011 Documenta*on de logiciel 33
La documenta*on pour un logiciel existant
PLAN 1. La documenta=on pour un nouveau logiciel
a) Expression des besoins ou Analyse fonc=onnelle b) Architecture/Concep=on c) Documenta=on technique ou détaillée d) Manuels e) Valorisa=on/Diffusion f) Aspects pra=ques de mise en oeuvre g) Quels documents produire en lien avec le contexte de développement
et d’u=lisa=on ? 2. La documenta=on pour un logiciel existant
a) Pré-‐requis b) Comprendre le fonc=onnement c) Manuels à produire/compléter
3. Mise en œuvre: analyse et proposi=ons
09/12/2011 Documenta*on de logiciel 34
Ques*ons de Laurent : posi*onnement pour la
documenta*on du logiciel • la taille de l'équipe (informa*cien travaillant seul ou à
plusieurs sur le projet) • travail développé uniquement en interne ou avec de la
main d’œuvre externe (CDD, stagiaire, société de service, autres services ...)
• le projet démarre et est nouveau, ou c'est une reprise/maintenance d'un logiciel existant (pas, peu ou bien documenté, développeurs ini*aux joignables ou non ...)
• u*lisateurs uniquement propres à l'équipe qui développe, pour une autre équipe, pour un département, l'INRA, ou diffusé à l'extérieur ? logiciel libre/propriétaire, gratuit ou payant ?
09/12/2011 Documenta*on de logiciel 35
Proposi*on d’une table de décisions pour la rédac*on de la documenta*on du logiciel
Doc Taille équipe
Travail réalisé Projet U=lisateurs Licence logiciel
1 >1 interne externe nouveau
reprise équipe Autre équipe
Départ. INRA
Tout INRA
ailleurs libre propriétaire
EB 1 2 1 2 1 -‐ 1 2 3 3 3 1 1
A 2 1 1 2 2 -‐ 1 1 1 1 2 1 1 DTD 1 2 1 3 1 1 1 1 2 2 2 3 2
M 1 2 1 2 1 1 1 1 2 2 2 2 2 V 1 1 1 ? 1 ? 1 1 2 2 2 2 2
09/12/2011 Documenta*on de logiciel 36
1: conseillé 2: nécessaire 3: indispensable
EB: Expression des besoins A: Architecture/Concep*on DTD: Documenta*on technique détaillée M: Manuels V: Valorisa*on et diffusion
Bibliographie • UML
– h_p://www.uml-‐sysml.org/uml – h_p://www.projet-‐plume.org/fr/ressource/uml
• Documenta*on logicielle – h_p://fr.wikipedia.org/wiki/Documenta*on_logicielle
• Cours ges*on de projet – Rémi Bachelet – h_p://rb.ec-‐lille.fr/ges*on_projet.htm
• Expression des besoins – h_p://www.lifl.fr/~dumoulin/enseign/2010-‐2011/coa/patrons/GuideDossierExpressionBE.pdf
• Méthode APTE – h_p://www.techno-‐science.net/?onglet=glossaire&defini*on=10849 – h_p://www.methode-‐apte.com/
09/12/2011 37 Documenta*on de logiciel