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