Comment écrire des release notes que les gens lisent

Pour écrire des release notes que les gens lisent, répondez à une question par entrée : qu’est-ce que la lectrice peut faire maintenant qu’elle ne pouvait pas avant, et que doit-elle faire à ce sujet. Mettez en premier tout ce qui a une échéance, nommez qui est concerné, dites “aucune action requise” quand c’est vrai, et sautez les versions qui n’ont rien à dire. Tout le reste de cette page est cette règle appliquée.

Corrections de bugs et améliorations de performance.

Chaque produit a publié ça un jour. La cause est rarement la paresse : c’est ce qu’on obtient quand les release notes sont écrites de l’intérieur, par quelqu’un qui a passé deux semaines dans le diff et ne peut plus voir quelles parties intéresseraient un inconnu. Un meilleur ton ne réglera pas ça ; répondre à la question, oui.

Que devraient inclure des release notes ?

Les release notes devraient inclure, pour chaque changement qui mérite d’être mentionné : ce que la lectrice peut faire maintenant, qui est concerné, ce qu’elle doit faire (y compris “rien”), et quand entre en vigueur ce qui a une échéance. Elles ne devraient pas inclure de numéros de tickets internes, de noms de composants que seule l’équipe utilise, ou un numéro de version comme seul titre.

La séparation entre une release note et une entrée de changelog est ce qui rend cette liste possible : le changelog garde tout, donc les notes peuvent laisser des choses de côté. Des exemples annotés de chaque type d’entrée sont rassemblés dans exemples de release notes.

La question à laquelle répond chaque entrée

Qu’est-ce que la lectrice peut faire maintenant qu’elle ne pouvait pas avant, et que doit-elle faire à ce sujet ?

Si une entrée ne peut pas répondre à ça, elle appartient au changelog et non aux release notes. Les deux moitiés comptent. La première moitié, c’est la valeur. La deuxième moitié, c’est celle que les équipes oublient, et c’est celle qui génère des tickets de support quand elle manque.

Deux exemples de la seconde moitié qui fait un vrai travail :

• “Les webhooks existants continuent de fonctionner jusqu’au 1er novembre. Après cette date, les payloads non signés seront rejetés.”
• “Aucune action requise. Les exports existants sont automatiquement réencodés la prochaine fois que vous les ouvrez.”

Le second dit explicitement “aucune action requise”. Cette phrase vaut la peine d’être écrite à chaque fois, parce qu’une lectrice qui ne la trouve pas suppose le pire.

Comment devrait-on ordonner des release notes ?

Ordonnez-les par conséquence pour la lectrice, jamais par la partie du système qui a changé. Regrouper par API, dashboard, mobile et infrastructure, c’est votre organigramme, pas le problème de la lectrice.

1. Les changements cassants et tout ce qui a une échéance. En premier, toujours, même si c’est petit. Si une lectrice arrête de lire après une ligne, c’est celle-là qu’elle devait avoir lue. Si l’échéance est un sunset, l’entrée devrait ressembler à un avis de dépréciation.
2. Ce qui est nouveau et qu’elles voudront. Un par paragraphe, avec le résultat dans la première proposition.
3. Ce qui s’est amélioré. Les bugs signalés, les limites relevées, les choses qui étaient lentes.
4. Tout le reste, en liste. Mises à jour de dépendances, refactors internes, copy mineur. Une ligne chacune. Personne ne lit cette section, et elle devrait quand même être là, parce que la personne qui la cherche en a vraiment besoin.

La réécriture

Avant :

v4.2.0 Correction d’un problème où l’endpoint POST /exports renvoyait de manière intermittente 500 sous charge. Refactorisation du worker d’export. Mise à jour de node-pg en 8.11. Amélioration de la gestion d’erreurs dans le sérialiseur CSV.

Après :

Les exports ne plantent plus sur les gros comptes. Les comptes de plus de 50 000 lignes environ pouvaient recevoir un 500 au démarrage d’un export, plus souvent en fin de mois. C’est corrigé, et les exports de toute taille se relancent maintenant tout seuls plutôt que d’échouer. Aucune action requise, et tout export qui a échoué la semaine dernière peut simplement être relancé.

Aussi dans la 4.2.0 : node-pg 8.11, erreurs plus claires dans le sérialiseur CSV.

Même version. La seconde nomme le compte concerné, le moment où c’était le pire, ce qui a changé, et quoi faire. La mise à jour de dépendance n’a pas disparu, elle a juste cessé d’être le titre. L’article bonnes pratiques des release notes a le reste des règles que suit cette réécriture, chacune avec ce qu’il en coûte de la sauter.

Choses qui valent la peine d’être supprimées

• “Nous sommes ravis d’annoncer.” La lectrice n’est pas encore ravie. Gagnez-la dans la phrase suivante.
• Numéros de tickets internes. PROJ-4471 ne signifie rien hors de votre tracker. Si l’entrée a besoin d’une référence, liez la page de doc.
• Noms de composants que seule votre équipe utilise. Si vous avez renommé le “pipeline d’ingest”, dites “imports”.
• Un numéro de version comme seul titre. v4.2.0 est une étiquette d’archivage, pas un résumé.
• Captures d’écran d’une page de réglages que personne n’a jamais visitée. Montrez ce qui a changé, en usage.

À quelle fréquence devrait-on publier des release notes ?

Publiez quand quelque chose s’est passé, pas selon un calendrier. Des notes qui arrivent à chaque version entraînent tout le monde à les ignorer. Des notes qui arrivent quand quelque chose s’est passé se font ouvrir. C’est correct, et généralement juste, de livrer une version sans aucune note et de faire rouler ses entrées dans le prochain lot qui a un titre qui vaut la peine d’être lu.

Le changelog continue de tout enregistrer. C’est la répartition du travail : le changelog est complet, les notes sont sélectives. Si vous gardez le changelog structuré au fil de l’eau, écrire les notes devient de la sélection et de la réécriture plutôt que de l’archéologie.

La release notes template est la forme qu’on utilise pour l’étape de sélection, et exemples de changelog rassemble des entrées d’équipes dont le changelog est assez bon pour en dériver des notes.

Tout ça suppose une page qu’on contrôle entièrement, sans limite de longueur et avec des liens qui fonctionnent. Release notes mobiles couvre ce qui change quand la surface est une fiche App Store ou Play Store. Release notes d’urgence couvre l’autre exception : ce qui change quand il ne reste plus du tout de temps pour suivre le processus normal de rédaction.

Un test avant de publier

Lisez les notes comme quelqu’un qui a été en vacances deux semaines et a 40 secondes. Si dans ce temps, cette personne ne peut pas dire si quelque chose lui est demandé, les notes ne sont pas finies, aussi précises soient-elles.

FAQ

Combien de temps devraient durer des release notes ? Autant que le nécessitent les changements à conséquences, et pas une ligne de plus. Une version avec un changement cassant et deux améliorations, c’est trois paragraphes. Gonfler une version tranquille pour la faire paraître substantielle, c’est comment les lecteurs apprennent à sauter les notes.

Qui devrait écrire les release notes ? La personne qui comprend le changement, éditée par quelqu’un qui ne le comprend pas. L’ingénieure sait ce qui a changé ; l’éditrice sait ce qu’un inconnu comprendra de travers. Écrire l’entrée au moment du merge, pendant que l’ingénieure s’en souvient encore, est la pratique qui rend tout ça bon marché.

Les release notes devraient-elles inclure des corrections de bugs ? Oui, celles que quelqu’un a signalées ou subies. Indiquez le symptôme vu par la lectrice, pas la cause. “Les exports de plus de 50 000 lignes échouaient” est une correction qu’une lectrice reconnaît ; “correction d’une race condition dans le worker d’export” est un message de commit.

Quelle est la différence entre des release notes et un changelog ? Le changelog est le registre complet et continu ; les release notes sont le message sélectionné sur une version, écrit pour des gens qui n’ont pas encore décidé si ça les intéresse. La réponse plus longue est dans changelog vs release notes.

Les affirmations techniques de cet article n'ont pas été vérifiées de façon indépendante. Si quelque chose est faux, dis-le-nous et nous le corrigerons.

À voir sur changeloop : Modèle de release notes, Exemples de changelog