![Page 1: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/1.jpg)
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
![Page 2: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/2.jpg)
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
![Page 3: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/3.jpg)
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
![Page 4: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/4.jpg)
09/12/2011 Documenta*on de logiciel 4
OUTILS PROJETS : Analyse Fonc7onnelle Rémi Bachelet – Ecole Centrale de Lille – mai 2011
![Page 5: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/5.jpg)
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
![Page 6: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/6.jpg)
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
![Page 7: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/7.jpg)
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
![Page 8: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/8.jpg)
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
![Page 9: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/9.jpg)
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
![Page 10: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/10.jpg)
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
![Page 11: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/11.jpg)
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
![Page 12: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/12.jpg)
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
![Page 13: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/13.jpg)
Contexte du problème à traiter
09/12/2011 Documenta*on de logiciel 13
![Page 14: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/14.jpg)
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
![Page 15: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/15.jpg)
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
![Page 16: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/16.jpg)
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
![Page 17: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/17.jpg)
« 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 ?
![Page 18: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/18.jpg)
« 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
![Page 19: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/19.jpg)
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
![Page 20: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/20.jpg)
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
![Page 21: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/21.jpg)
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
![Page 22: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/22.jpg)
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
![Page 23: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/23.jpg)
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
![Page 24: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/24.jpg)
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
![Page 25: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/25.jpg)
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
![Page 26: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/26.jpg)
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
![Page 27: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/27.jpg)
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
![Page 28: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/28.jpg)
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
![Page 29: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/29.jpg)
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
![Page 30: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/30.jpg)
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
![Page 31: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/31.jpg)
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
![Page 32: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/32.jpg)
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
![Page 33: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/33.jpg)
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
![Page 34: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/34.jpg)
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
![Page 35: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/35.jpg)
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
![Page 36: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/36.jpg)
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
![Page 37: Documentaon+du+logiciel+ - Institut national de la recherche …idl.pepi.inra.fr/attachments/article/46/Documentation... · 2011. 12. 13. · Participer à un projet Utilisateurs](https://reader033.vdokument.com/reader033/viewer/2022053023/605670e23dd68d49a4437f35/html5/thumbnails/37.jpg)
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