La plupart des changelogs sont écrits pour le mauvais lecteur. Ils sont écrits pour l’équipe qui a livré le travail : précis, exhaustifs et organisés par pull request. Le client qui en ouvre un se pose une question bien plus simple : qu’est-ce qui a changé pour moi, et est-ce que je dois m’en soucier ?
L’an dernier, nous avons reconstruit le changelog de Lagoon autour de cette question. L’audience est passée d’une erreur d’arrondi à la deuxième page la plus visitée du site, devant la page tarifs. Les tickets de support ont commencé à nous citer des entrées. Rien n’a changé dans le produit lui-même. Seuls l’écriture et le pipeline ont changé. Voici ce que nous en avons retenu.
Écrivez le changement, pas le commit
Le message de commit dit ce qui est arrivé au code. L’entrée de changelog dit ce qui est arrivé au lecteur. « Refactorisation du worker d’ingestion pour le dédoublonnage multi-source », c’est un commit. « Les retours en double venant de Slack et de l’e-mail fusionnent désormais automatiquement », c’est une entrée. Même travail, phrase différente, et une seule des deux mérite un clic.
Le test que nous appliquons est simple : un client pourrait-il lire l’entrée à voix haute à un collègue et être compris sans le moindre contexte supplémentaire ? Si la réponse est non, l’entrée n’est pas encore traduite. La traduction, c’est tout le travail. Elle prend en général cinq minutes, et ce sont ces cinq minutes qui décident si la page sera lue.
Le format en trois lignes
Chaque entrée de notre changelog suit la même ossature, et c’est justement cette prévisibilité qui compte :
- Ce qui a changé, en une phrase qu’un client dirait vraiment à voix haute.
- Pourquoi c’est important, formulé autour d’une tâche que le lecteur accomplit déjà chaque semaine.
- Ce qu’il faut faire ensuite, même quand la réponse est « rien, c’est déjà actif chez vous ».
Les lecteurs assimilent le rythme en deux visites. Ils parcourent vingt entrées en une minute et ne s’arrêtent que là où leur propre flux de travail apparaît. Ce survol n’est pas un défaut d’attention. C’est la fonctionnalité.
Si un lecteur ne sait pas ce qu’il doit faire différemment après avoir lu une entrée, l’entrée n’est pas terminée.
Les petites entrées battent les grands récapitulatifs
Nous gardions autrefois nos annonces pour un récapitulatif mensuel, en partant du principe que le regroupement donnait au produit un air plus imposant. En pratique, cela donnait à chaque changement un air de retard. Un correctif livré le mardi et annoncé trois semaines plus tard passe pour une pensée après coup. Désormais, une entrée part le jour même du changement, aussi petit soit-il. L’élan, il se trouve, se communique par la fréquence, pas par le volume.
Traitez le changelog comme un artefact de build
La discipline d’écriture n’a tenu qu’à partir du moment où nous avons intégré le changelog à la base de code, au lieu d’en faire une corvée marketing qui traînait dans le dossier brouillons de quelqu’un.
Les entrées sont des fichiers Markdown qui vivent dans le dépôt, juste à côté du code qu’elles décrivent. Elles sont écrites par l’ingénieur qui a réalisé le changement, relues comme n’importe quel autre fichier et publiées automatiquement à la fusion. Une pull request visible par les clients et dépourvue d’entrée échoue à la checklist, exactement comme si des tests manquaient.
Cela produit trois effets discrets mais importants. Cela supprime le passage de relais, donc plus rien n’attend l’agenda d’une deuxième équipe. Cela garde l’auteur honnête, parce que la personne qui connaît les réserves est celle qui écrit la phrase. Et cela donne un relecteur à l’entrée, si bien que le ton et la clarté reçoivent le même examen que la logique.
Laissez le lecteur s’abonner à sa façon
La page fait référence, mais presque personne ne rafraîchit une page. Nous publions les mêmes entrées dans un flux RSS, dans un résumé Slack pour les espaces de travail connectés, et dans un court e-mail mensuel pour tous les autres. Une source, plusieurs surfaces. L’entrée est écrite une fois et jamais réécrite canal par canal, ce qui est la seule manière pour que l’habitude survive à un trimestre chargé.
Ce que cela a changé pour nous
La surprise n’a pas été le trafic. C’est de découvrir pour qui la page s’est mise à travailler. Les commerciaux envoient des liens vers le changelog dans leurs relances, parce que la page prouve que le produit est vivant. Le support résout les tickets « comment fait-on pour… » en pointant l’entrée qui a introduit la fonctionnalité. Les discussions de renouvellement s’ouvrent en faisant défiler tout ce qui a été livré depuis le dernier contrat, ce qui est une entrée en matière bien plus solide qu’un jeu de diapositives.
Un changelog que les gens lisent n’est pas une affaire de talent d’écriture. C’est une décision sur le destinataire de la page, plus un pipeline qui fait du bon comportement le comportement par défaut. Tranchez en faveur du lecteur, câblez-le dans le build, et l’audience suivra.