Studio Lucarne, une agence spécialisée dans les sites éditoriaux, gère un plugin interne regroupant vingt-deux blocs maison, réutilisés d’un projet client à l’autre. Chaque nouvelle recrue passait ses deux premières semaines à redécouvrir, bloc par bloc, ce que fait attributs.variante ou pourquoi tel bloc dépend d’un autre. L’équipe a testé trois approches de documentation sur ce même plugin, à des moments différents, pour comparer ce qui tenait réellement dans la durée.
Le README à la racine de chaque bloc
Première tentative : un fichier README.md dans le dossier de chaque bloc, décrivant son rôle métier, ses dépendances avec d’autres blocs, et des captures d’écran. Ce format a bien fonctionné pour le contexte que le code seul ne peut pas porter : pourquoi ce bloc existe, dans quel projet il a été conçu à l’origine, quelles limites ont été acceptées consciemment.
En revanche, le README a vite divergé du code sur les détails techniques : un attribut renommé lors d’un refactoring n’était mis à jour dans le README que si quelqu’un y pensait, ce qui n’arrivait pas systématiquement. Au bout de six mois, environ un tiers des README contenaient au moins une information technique obsolète.
La JSDoc directement dans le code
Deuxième approche, en réaction à la précédente : documenter chaque composant et chaque fonction utilitaire avec des commentaires JSDoc standards, directement au-dessus de la déclaration :
/**
* Affiche un encart de mise en avant d'article avec image et texte.
*
* @param {Object} props
* @param {string} props.variante - 'horizontal' ou 'vertical'.
* @param {number} props.articleId - Identifiant de l'article mis en avant.
* @return {JSX.Element} Le composant d'édition du bloc.
*/
function Edit({ variante, articleId }) {
// ...
}
Cette approche a un avantage décisif : elle est physiquement impossible à ignorer lors d’une modification, puisqu’elle se trouve juste au-dessus du code qu’on modifie. Le taux de désynchronisation a chuté drastiquement par rapport aux README. Sa limite : elle documente bien l’API d’un composant isolé, mais peu le contexte global (pourquoi deux blocs existent en parallèle, quand choisir l’un plutôt que l’autre).
Storybook pour les composants visuels partagés
Troisième étape, réservée aux composants d’interface réutilisés entre plusieurs blocs (un sélecteur de couleur maison, un composant de gestion d’onglets) : Storybook, avec une story par variante visuelle. L’investissement de mise en place (configuration du build, écriture des premières stories) a représenté environ trois jours pour l’équipe, non négligeable pour une agence de cette taille.
Le retour sur cet investissement n’est apparu qu’à partir d’un certain volume : en dessous d’une demi-douzaine de composants partagés, Storybook ajoutait plus de charge de maintenance (mise à jour des stories à chaque changement de props) qu’il n’en économisait. Au-delà, sur les composants réellement transverses, il a évité plusieurs redémarrages de développement quand une nouvelle recrue cherchait « est-ce qu’un composant de ce type existe déjà ».
Ce que l’équipe a finalement retenu
| Approche | Force | Limite observée |
|---|---|---|
| README | Contexte métier, historique du choix | Se désynchronise vite du code technique |
| JSDoc | Toujours à jour car collée au code | Ne documente pas le pourquoi global |
| Storybook | Catalogue visuel navigable des composants partagés | Rentable seulement à partir d’un vrai volume |
La combinaison retenue aujourd’hui : un README court par bloc, limité au contexte métier et volontairement dépourvu de détails techniques précis, de la JSDoc systématique sur chaque composant et fonction exportée, et Storybook réservé aux composants d’interface génériques partagés par plus de trois blocs.
Une documentation qui peut mentir sans que personne ne s’en aperçoive finit toujours par mentir.
Ce que cet article ne couvre pas
Les tests automatisés des blocs (Jest, tests de bout en bout) relèvent d’une problématique différente, déjà traitée séparément : ils vérifient un comportement, la documentation explique une intention. Les deux sont complémentaires mais répondent à des besoins distincts d’une équipe qui grandit.
Notre verdict
Aucune des trois approches, seule, n’a suffi durablement chez Studio Lucarne. La bonne réponse dépend moins d’un choix unique que d’assigner à chaque type d’information le format qui a le plus de chances de rester vrai dans le temps.
