Documentation des projets libres : bonnes pratiques

Inspirée d'un article de Framablog qui recense 13 problèmes que les gens détestent rencontrer dans les projets libres, la liste ci-dessous fait une synthèse des bonnes pratiques à appliquer pour bien documenter un projet. Cette liste peut également être utilisée comme signification du fini pour des projets agiles reposant sur Scrum.

1. Soigner le README/LISEZMOI, afin de présenter le projet.
1. Le README explique ce que le projet fait.
2. Le README explique pour qui il est fait.
3. Le README explique sur quel matériel ou plateforme il tourne.
4. Le README explique toutes les dépendances majeures.
5. Le README explique comment l’installer, ou fournit un accompagnement de chaque étape à la suivante.
2. Publier la documentation en ligne, afin de la rendre facile d'accès.
1. La documentation est publiée en ligne.
2. La documentation, FAQ compris, est disponible sur le même site que le projet.
3. Publier la documentation dans un format consultable hors ligne, afin qu'elle puisse être toujours accessible à l'utilisateur.
1. La documentation (complète, et pas seulement une partie) est téléchargeable dans un format facile à parcourir.
2. La documentation complète est distribuée avec les livrables du projet.
3. La documentation est adaptée au projet. Par exemple : man pour connaître le fonctionnement d'un outil en ligne de commande.
4. Distribuer la documentation dans des paquets séparés du projet, afin que l'utilisateur puisse choisir les livrables qui lui sont utiles sans surcharger sa bande passante ou son disque dur.
1. Un rappel signifie à l'utilisateur que la documentation et le projet sont distribués dans des paquets distincts. Par exemple : page de démarrage, installateur, release notes, etc.
2. La documentation indique à l'utilisateur comment récupérer les paquets optionnels de la documentation du projet, dans le cas où il pourrait en avoir besoin.
5. Illustrer la documentation par des captures d'écran, afin de guider l'utilisateur.
1. Les résultats à obtenir en suivant la documentation sont exposés sous forme de captures d'écran.
2. Un aperçu du projet est montré sous forme de vidéo.
3. Dans le cas d'un processus complexe, chaque étape est accompagnée d'une vidéo.
6. Ajouter des exemples concrets et réalistes, afin de montrer l'utilité du projet.
1. Les exemples sont directement issus du monde réel et fondés sur un histoire d'utilisateur.
2. Les exemples de la documentation sont corrects, fonctionnels, testés et commentés.
3. La documentation comporte une section dédiée aux exemples, voire un livre de cuisine.
4. A la fin des exemples, la documentation invite les utilisateurs à envoyer du code qui fonctionne : les meilleurs exemples seront publiés.
7. Créer des liens et références adéquats dans la documentation, afin de faciliter la lecture et la compréhension.
1. Lors du premier usage d'un terme, une brève explication de ce terme est fournie.
2. Chaque fois qu'un concept est cité, un hyperlien renvoie vers la section du manuel l'expliquant.
8. Ajouter une introduction à la documentation, afin d'aider les nouveaux utilisateurs à comprendre le projet.
1. L'introduction est une page séparée de la documentation.
2. L'introduction comporte des exemples de manipulations simples et faciles du projet.
3. Un document de démarrage ou de mise en route séparé donne à l’utilisateur une compréhension rapide du projet.
9. Améliorer la documentation en fonction des retours des utilisateurs, afin que tous ceux qui se posent la même question trouvent d'eux-mêmes des réponses.
1. En cas de manque, chaque question posée est traitée dans la FAQ.
2. En cas de confusion, la documentation est clarifiée.
3. Si une partie de la documentation répondant à la question n'a pas été consultée, des liens sont ajoutés ailleurs dans la documentation : page d'introduction, table des matières, etc.
4. Les retours d'utilisateurs sont favorisés par plusieurs canaux. Par exemple : liste de diffusion, forum, canal IRC, brancher une Google Alert sur StackOverflow, blog, etc.
10. Accepter les entrées des utilisateurs comme contributions à la documentation, afin d'enrichir la documentation et de renforcer la dimension communautaire du projet.
1. Les utilisateurs peuvent commenter les pages de la documentation.
2. Les commentaires des utilisateurs sont intégrés à la documentation hors ligne du projet.
3. Un utilisateur peut lire la documentation avec ou sans les commentaires.
11. Donner un aperçu des fonctionnalités du projet avant l'installation, afin que l'utilisateur sache pourquoi il devrait l'adopter.
1. La documentation fournit une liste des fonctionnalités du projet.
2. Les fonctionnalités sont démontrées au travers d'une page de captures d'écran ou d'exemples d'utilisation.
12. Rédiger la documentation en fonction des besoins des utilisateurs, afin qu'elle réponde vraiment à leurs interrogations et préoccupations.
1. Le journal des modifications (ChangeLog) liste les nouvelles fonctionnalités, les problèmes résolus et les incompatibilités potentielles.
2. Chaque fonction est accompagnée d'une description explicative.
13. Travailler la lisibilité de la documentation, afin de faciliter l'apprentissage.
1. La documentation est correctement écrite, facile à lire et présente bien à l'écran.
2. Certaines informations sont répétées, dès lors qu'elles sont vitales à la compréhension des nouveaux utilisateurs.

Cette liste est également disponible dans son format original, sous forme d'une carte heuristique.

Bonnes pratiques pour la documentation d'un projet

N'hésitez pas à améliorer cette liste en me faisant part de vos remarques en commentaire de ce billet.

Liens :

• 13 Things People Hate about Your Open Source Docs
• 13 points que les gens détestent sur la documentation de votre projet libre

Given-When-Then comme pratique agile

Certains frameworks de test fonctionnel orientés vers BDD (Behaviour-Driven Development) implémentent nativement la séparation des étapes d'un test selon ce schéma :

Given / Étant donné [un contexte]

When / Quand [certains événements surviennent]

Then / Alors [on obtient les résultats attendus]

Par exemple, JBehave le propose dans son système d'annotations (@Given, @When, @Then), afin de composer l'écriture d'un "story test" en Java.

Mais ces mots-clés peuvent servir également à bien identifier les étapes à l'intérieur d'autres types de tests : unitaires ou d'intégration, avec JUnit par exemple. En effet, les annotations de JUnit ne sont pas toujours suffisantes : @Before (préparation), @Test (exécution + vérification) et @After (nettoyage) correspondent au cycle ci-dessous.

Tester en 4 étapes

Or, dans un test JUnit, rien ne distingue les étapes "Quand" et "Alors", sinon l'ordre d'écriture. De plus, quand une classe de test comporte plusieurs méthodes @Test, il est souvent nécessaire d'y ajouter quelques lignes supplémentaires pour finir la préparation du contexte ("Étant donné").

En tant que pratique, Given-When-Then a l'avantage de donner un guide pour mieux structurer son cas de test, d'inciter à n'écrire qu'un cas par méthode de test, ainsi que d'améliorer la lisibilité du code.

De manière à en généraliser l'usage, quoi de mieux que de l'intégrer directement dans son IDE ?

Avec Eclipse IDE, dans le menu "Windows / Preferences" :

• accéder au sujet "Java / Editor / Templates",
• créer un nouveau template en cliquant sur "New",
• configurer le template comme ci-dessous :
  
• dans votre méthode de test, taper tout ou partie de "givenwhenthen" et laisser l’auto-complétion faire le reste.

Il est aussi possible d'importer un template, en cliquant sur le bouton "Import" et en sélectionnant ce fichier.

Liens :

• Given - When - Then, Référentiel de l'Institut Agile

Etats des objets Hibernate (poster)

Ce poster comprend :

• La définition des états Hibernate : objets volatiles ("transient"), persistants et détachés.
• L'effet des opérations supportées par la session Hibernate lors des transitions d'état.
• Des extraits de code montrant où peuvent intervenir les états entre les différentes couches d'une application 3-tiers (couche de présentation, couche de service et couche de persistance).

États des objets Hibernate

Liens :

• Hibernate Documentation

Lister les ports ouverts dans un batch

Quelques commandes utiles

• Afficher la date : date /t, ou bien : echo %date%
• Afficher l'heure : time /t, ou bien : echo %time%
• Afficher toutes les connexions TCP actives, avec le nom du programme impliqué dans la création de chaque connexion et ports ouverts, les adresses et les ports étant affichés au format numérique : netstat -bon
• Lancer une nouvelle instance de l'interpréteur de commande Windows, avec fermeture en fin d'exécution : cmd /C

Le tout dans un batch :

echo off

set dateTime=%date%T%time%
set output=netstat-report.txt

(
    echo %dateTime%
    cmd /C netstat -bon
) > %output%

Les résultats peuvent ensuite être lus dans le fichier "netstat-report.txt".
Remarque : Si l'utilitaire netstat n'est pas exécuté avec cmd, le fichier de rapport ne contiendra pas la sortie de netstat.

Liens :

• Netstat sur Wikipédia

User Story ou Use Case ?

Entre User Story et Use Case, la différence ou la séparation est parfois confuse, et il me paraît intéressant de bien situer les deux en terme de similitudes, de spécificités et de complémentarité. Pour rappel, voici quelques définitions utiles se rapportant au sujet des user stories et des use cases, avant de les comparer.

Définition d'une Feature :

Une feature est un service fourni par le système, observable de l'extérieur, qui répond à un besoin, et dont la description se situe à un niveau tel que toutes les parties prenantes comprennent facilement ce dont il s'agit.

On emploie également dans le domaine de l'ingénierie des exigences les termes suivants : theme, epic, minimal marketable feature (MMF).

Exemples d'atelier pour identifier les features :

• Product Box / Boîte du Produit
• Remember the Future / Souvenir du Futur

Définition d'une User Story (ou histoire utilisateur) :

Une user story est une fonctionnalité élémentaire décrite du point de vue de l'utilisateur. Elle apporte de la valeur à l'utilisateur et peut être réalisée en moins d'une itération de deux semaines, c'est-à-dire quelques jours tout au plus. Les US sont obtenues par la décomposition des features. L'écriture d'une US s'appuie sur la formalisation suivante :

En tant que <rôle>, je peux <action>, afin de <justification>.

User Story : matrice Rôle - Fonctionnalité - Bénéfice

Avec 3 attributs récurrents :

• un rôle,
• une action : le but fonctionnel,
• une justification (parfois facultative, car elle peut être évidente),
• la plus-value métier, représentant le bénéfice que va tirer l'utilisateur de la user story,
• le coût en story points, c'est-à-dire l'estimation de l'effort nécessaire à la réalisation de la user story.

Et éventuellement des attributs complémentaires :

• une priorité déduite de la plus-value métier et du coût,
• La fréquence d'utilisation de la US par le rôle : plus grande est la fréquence d'utilisation, plus important sera le soin apporté aux tests (tests unitaires, d'intégration, de charge, etc).
• Des informations complémentaires : texte, schéma, diagramme.

Et toujours les tests d'acceptation (story tests) associés à la US : en fin d'itération, la US est considérée finie seulement si tous les tests d'acceptation sont validés. Les tests d'acceptation, ou conditions de satisfaction, ont eux-mêmes leur formalisme :

Étant donné... <pré-condition : état du système>
Quand... <événement : acteur + action>
Alors... <résultat observable de l'extérieur>
[Et... <autre résultat observable>]

Définition d'un Use Case (ou cas d'utilisation) :

Un use case est une description des interactions qui vont permettre à l'acteur d'atteindre son objectif en utilisant le système. Les interactions sont regroupées en scénarii. Un acteur est une entité décrite par son rôle, ses besoins et ses capacités.

Rédaction d'un cas d'utilisation :

• Fiche récapitulative :
• Titre,
• Identifiant,
• Acteurs,
• Description.
• Préconditions
• Post-conditions
• Scénario principal : séquence d'étapes ordonnées dans le temps (3 à 9 étapes).
• Scénarii alternatifs éventuels : variations / exceptions, cas d'erreur et leur gestion.

Un cas d'utilisation ne doit pas se réduire à l'IHM, ce qui masquerait les interactions du système avec d'autres acteurs que l'utilisateur final.

Le diagramme des cas d'utilisation comprend :

• un ou des acteurs, représentés par des pictogrammes humanoïdes,
• des cas d'utilisation, représentés par des ellipses,
• des relations, représentées par des traits :
• relations simples (trait continu), 
• inclusions (traits pointillés terminés par une flèche et stéréotype "includes"),
• extensions (traits pointillés terminés par une flèche et stéréotype "extends"),
• généralisations (ou spécialisations, ou héritages) (trait continu terminé par une flèche triangulaire).

Qu'il s'agisse de User Story ou de Use Case, les deux techniques servent à appréhender les besoins des utilisateurs en terme d'interaction avec un système, mais leurs manières de le faire divergent en de nombreuses occasions.

	User Story	Use Case
Finalité	En association avec les tests d'acceptation, rédiger les exigences fonctionnelles du point de vue de l'utilisateur. Faciliter l'estimation et la planification : les US décomposées peuvent être planifiées dans des itérations différentes. Comme éléments du backlog de produit, les US sont orientées vers la gestion et le suivi des projets.	Seulement recueillir l'expression des besoins et rédiger les spécifications détaillées des exigences fonctionnelles sous forme de processus métier.
Traçabilité	US conservée dans le Backlog de produit.	UC conservé dans le document des spécifications fonctionnelles.
Granularité	Fine : une fonctionnalité élémentaire. Une US peut être une partie d'un UC : tout ou partie d'un scénario, ou éclatée dans plusieurs scénarii. Implémentée et testée en moins d'une itération.	Grande : une macro-fonctionnalité qui en réunit de plus petites. Implémenté et testé en une ou plusieurs itérations.
Formalisme	Phrase composée de 3 attributs : rôle ("qui ?"), action ("quoi ?"), justification ("pourquoi ?"), et complétée par des tests d'acceptation.	Le formalisme est défini par UML. Scénarii constitués d'une séquence d'actions ou d'événements. Répondent à "qui ?" et "quoi ?". Les UC sont regroupés dans un diagramme des cas d'utilisation.
Expression	Description brève, facile à comprendre, dans le langage de tous les jours ou du métier (mais sans jargon technique).	Quantité importante d'informations, dans le langage spécifique de l'utilisateur final ou de l'expert du domaine métier. (Une demi-page pour un UC court, jusqu'à 2 pages pour un long)
Effort	Émergence rapide des exigences. Facile à écrire avec ou par des utilisateurs ou des clients.	Les UC nécessitent un long travail d'analyse et de formalisation, afin de décrire un système entier et pensé dans son intégralité.
Complétude	Les tests d'acceptation fournissent les conditions de satisfaction sous forme de scénarii courts pour valider une US.	Le scénario principal décrit le comportement nominal. Pour le reste, les scénarii alternatifs et d'erreur viennent combler les manques.
Maintenabilité	Facile à maintenir, car le format est synthétique.	Difficile à maintenir, car le format implique un contenu très conséquent. De plus, les UC mélangent les interactions et les règles métier, ce qui pose problème quand les besoins évoluent.
Focus	Valeur métier pour l'utilisateur final.	Interactions entre l'utilisateur final et le système.
Visibilité du contexte global	Difficile de lier les US les unes aux autres. Une partie du contexte est fournie par les features et la vision du produit.	Les scénarii montrent l'enchaînement temporel des actions.
Culture de travail	Adaptée au travail collaboratif et à des échanges de proximité. Favorable à l'émergence de débats et à la négociation.	Adapté à des échanges distants et contractuels.
Tests	Les US contiennent déjà les tests d'acceptation à réaliser pendant les développements, puis lors de la démonstration pour la validation avec le Product Owner. Cf. ATDD.	Les UC permettent de préparer les tests de recette, car les scénarii donnent les parcours à réaliser au cours des tests fonctionnels. Mais ils n'indiquent pas les critères d'acceptation pour statuer.
Relation avec d'autres méthodes	Technique issue de l'eXtreme Programming et associée aux méthodes agiles.	Technique associée au Processus Unifié.
Auteur de référence	Mike Cohn	Alistair Cockburn

Ainsi, on constate déjà un certain nombre d'impacts selon le choix qui sera fait entre User Story et Use Case :

• Impact sur la vision du produit :
• Les US expliquent ce que doit faire un système, mais aussi pourquoi. Les US sont regroupées au travers des features dont elles sont issues.
• Les UC expliquent bien ce que doit faire un système, mais pas pourquoi il le fait. Les UC sont liés entre eux par le diagramme des cas d'utilisation, et leurs scénarii relient les fonctionnalités entre elles.
• Impact sur les cycles des livraisons :
• Cycle court avec les US et livraison au plus tôt de leur plus-value métier pour un retour sur investissement plus tôt et plus rapide ;
• Livraisons plus espacées avec les UC.
• Impact sur le processus de développement :
• Longue phase de spécification avec les UC suivie de phases distinctes définies par le processus (RUP, cycle en V ou cascade) ;
• Réalisation par petits périmètres fonctionnels, qui autorise un transfert continu et opportuniste de la connaissance métier vers l'équipe de développement, une collaboration entre toutes les parties prenantes à chaque itération, ainsi qu'un retour rapide du ressenti utilisateur permettant d'éventuels changements au plus tôt (et donc à moindre coût).
• Impact sur la validation ou recette :
• Les critères sont connus avant les développements avec les US, ce qui permet de limiter les interprétations ;
• Les critères sont exprimés après les développements avec les UC seuls comme exigences, ce qui nécessite une deuxième interprétation des exigences à la rédaction du cahier de recette, potentiellement différente, et donc une maintenance corrective accrue.

En revanche, il existe une complémentarité entre user story et use case, entre la vision du produit et la visibilité du contexte global. Dans la mesure où il serait possible de construire le scénario principal d'un cas d'utilisation sur une seule histoire utilisateur, on pourrait tirer parti d'un diagramme des cas d'utilisation reprenant différents items du backlog de produit.

Liens :

• Innovation Games
• Wikipédia : User Story, Cas d'utilisation, UML, Diagramme des cas d'utilisation
• Scrum, le guide pratique de la méthode agile la plus populaire, Claude Aubry
• UML 2 par la pratique, Pascal Roques
• Blog de Claude Aubry : Use-case et user story, User stories et use-cases
• Blog de Laurent Carbonnaux : User Story vs Use Case
• Matrice Rôle - Fonctionnalité - Bénéfice, Institut Agile