Documentaon+du+logiciel+ - Institut national de la recherche...

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


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



•  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)




•  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)



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)


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


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).


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


Contexte du problème à traiter


But à a_eindre


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


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


« 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


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


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



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


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


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/


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


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 –  …..


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)


Aspects pra*ques de mise en œuvre …


•  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



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



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

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


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


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 »



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 ?


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


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/


Documentaon+du+logiciel+ - Institut national de la recherche...

Documents

Transcript of Documentaon+du+logiciel+ - Institut national de la recherche...