Lecture 3 minutes

Lors d'une conférence sur le Forum PHP, Sarah Haïm-Lubszanski nous parle de son cheval de bataille favori : la documentation.

La documentation, à quoi ça sert ?

Sarah nous rappelle qu’il est important de documenter tout logiciel que nous faisons. Par logiciel, elle désigne aussi bien une librairie publiée pour utilisation et intégration dans des outils par d’autres développeurs, qu’un site web, une application lourde ou une application en mode SAAS.

La documentation est importante pour la visibilité de nos développements, pour qu’ils soient utilisés et vivants !

Pourquoi mettre à disposition un outil si personne n’est capable de le comprendre et de l’utiliser ?

Cassons tout de suite le mythe racontant que la doc' est dans les commentaires du code. Non, les commentaires du code ne sont pas une documentation. Certes, ils sont utiles pour la maintenabilité du code, mais ils ne décrivent pas comment intégrer et utiliser correctement une librairie dans un projet pour un développeur. Ni comment exploiter tout le potentiel d'une fonctionnalité pour un utilisateur final.

Comment procéder ?

Sarah donne les étapes et outils pour écrire une documentation efficace, lisible. Elle nous explique aussi comment la mettre à jour au fur et à mesure des évolutions et l'améliorer continuellement.

Ainsi, il est important d’intégrer la rédaction de la documentation dans notre cycle de développement. Cela permet de la maintenir à jour tout au long des évolutions et de l'améliorer grâce aux retours obtenus de la part des utilisateurs.

Il existe des outils comme le framework Diátaxis pour nous aider dans ces tâches de rédaction. Il nous permet de structurer la documentation par type de contenu :

• Tutorials : orienté prise en main et apprentissage de base
• How-to : orienté réalisation d'une tâche précise
• Références : orienté description technique des éléments de l’application
• Explication : orienté explications détaillées des éléments de l’application

Et pour la forme ?

Le contenu est important, mais la présentation de celui-ci l’est tout autant. La doc' doit être lisible et agréable à lire (pour cela aussi il existe des outils !). Et si nous apprécions particulièrement la présentation d'une doc', n’hésitons pas à vous en inspirer !

Enfin, n'oublions pas d'impliquer le service marketing dans la construction de la documentation, notamment pour leur compétence en UX. Une équipe dédiée à la documentation de l'outil peut aussi être envisagée si cela répond à un enjeu stratégique... De cette façon, la documentation reste à jour et répond toujours aux besoins des utilisateurs !

Lien vers les slides de la présentation : https://www.slideshare.net/secret/1V6lifkGUKVHuN