Construire une page de changelog que l'on suit

Une page de changelog vaut la peine d’être construite quand quelqu’un y reviendrait. C’est une barre plus haute que d’en avoir simplement une, et c’est la barre où échouent la plupart : une page qui existe, est liée dans le pied de page, se met à jour par rafales et n’est visitée par personne sauf pendant un incident. Les décisions qui séparent les deux se prennent avant qu’aucun mot ne soit écrit, et concernent surtout où vit la page et ce qui d’autre est généré à partir du même contenu.

Qu’est-ce qu’une page de changelog ?

C’est la liste publique et datée de ce qui a changé dans un produit, sur une URL qui vous appartient. C’est l’une des cinq surfaces où peuvent apparaître les mêmes entrées, et la question utile n’est pas laquelle choisir mais laquelle est canonique et lesquelles en sont générées.

Choisissez une source canonique, publiez une fois, et générez le reste. Les équipes qui maintiennent la page et le widget séparément à la main finissent avec deux textes qui ne concordent pas, et c’est un client qui découvre l’écart.

Où une page de changelog devrait-elle vivre ?

Sur votre propre domaine, sur un chemin stable, avec chaque entrée adressable individuellement via un fragment ou son propre chemin. Les trois emplacements courants sont un chemin sur le site principal, un sous-domaine, et une section de la documentation. Un chemin sur le site principal est le choix par défaut contre lequel il faut argumenter, pas pour : il hérite de l’autorité du site, ne nécessite ni certificat ni DNS supplémentaire, et garde la page dans la même navigation que tout le reste.

Un sous-domaine est la bonne réponse quand la page est servie par un système différent du site marketing et que vous feriez sinon du proxy. Le coût est qu’il accumule de l’autorité séparément. Placer le changelog dans la doc est juste quand le public est développeur, pour la raison couverte dans changelog d’API : le lecteur y est en général déjà.

Ce qui compte plus que le choix, c’est que les entrées soient individuellement liables. Les gens lient des entrées dans des revues d’incidents et des tickets internes, et une entrée qui ne peut être liée que comme “le changelog, faites défiler” finit collée en capture d’écran à la place.

De quoi a besoin une page de changelog ?

Cinq choses, et sur les deux premières échouent la plupart des pages. Une entrée datée par changement, la plus récente en premier. Une catégorie ou étiquette par entrée pour pouvoir parcourir selon le type qui intéresse. Un permalien par entrée. Une voie d’abonnement. Une recherche ou un filtre au-delà d’une cinquantaine d’entrées.

Tout le reste est optionnel. Les captures d’écran aident et coûtent de l’entretien. Les noms d’auteurs bâtissent la confiance sur certains produits et du bruit sur d’autres. Les numéros de version comptent pour les appelants d’une API et pour presque personne d’autre. Keep a Changelog propose un choix par défaut raisonnable pour les étiquettes si vous n’avez pas de raison d’en inventer, et sa règle centrale est celle à garder même si vous jetez le reste : le journal est écrit pour des humains.

Groupez par date plutôt que par version quand votre produit livre en continu. Un lecteur qui scanne “était-ce avant ou après notre incident du neuf” cherche une date, et une page organisée par numéro de version l’oblige à faire du calcul.

Page ou widget in-app ?

Les deux, à partir d’une source. La page est où vivent la recherche, les liens et le registre long. Le widget est comment vous atteignez la majorité des utilisateurs qui ne visiteront jamais la page, et il fonctionne parce qu’il apparaît dans le produit qu’ils utilisent déjà.

L’échec du widget est l’interruption. Un badge qui exige de l’attention pour chaque entrée est écarté définitivement en une semaine, ce qui vous coûte le canal pour l’entrée qui comptait vraiment. Comptez les non lues depuis la dernière consultation, semez le compteur en silence à la première visite pour que personne ne soit accueilli par un badge d’un an d’historique, et laissez le lecteur l’ouvrir plutôt que de l’ouvrir pour lui.

Comment rendre une page de changelog lisible par machine ?

Publiez les mêmes entrées comme flux. Un flux JSON est l’option la plus simple pour tout ce qui le consomme en code, et un flux RSS est ce qu’attend un développeur abonné dans un lecteur. Les deux coûtent peu une fois les entrées structurées en données plutôt qu’en HTML écrit à la main, ce qui est l’argument réel pour garder la copie canonique structurée.

Balisez aussi la page. Les entrées sont des œuvres avec date et titre, et schema.org fournit le vocabulaire. Cela en vaut la peine pour la même raison que les permaliens : cela rend la page utilisable par des choses qui ne sont pas un navigateur, y compris le propre processus de release d’un client. Rien de tout ça ne fonctionne si les entrées sous-jacentes n’ont jamais été des données structurées dès le départ ; formats de fichier changelog couvre ce que coûte chacun de Markdown, JSON et YAML comme source de vérité dont ce flux et ce balisage sont réellement générés.

Une page de changelog aide-t-elle le SEO ?

Indirectement et lentement. Les entrées individuelles se positionnent rarement, car elles ne visent aucune requête que quelqu’un tape. La page gagne sa place via les liens : les entrées sont citées dans des réponses de support, des forums et des analyses d’incidents, et ces liens s’accumulent sur une URL qui vous appartient. Une page mise à jour chaque semaine pendant deux ans est aussi un signal de fraîcheur crédible pour le produit auquel elle appartient.

Ce qui ne fonctionne pas, c’est de traiter les entrées comme du content marketing. Une entrée gonflée à trois paragraphes pour l’allonger est pire dans son vrai travail, qui est de dire à un lecteur en une phrase si quelque chose qu’il utilise a changé. Si vous voulez que le changelog soutienne la recherche, mettez l’effort dans les permaliens, le flux et les liens internes vers lui, et gardez les entrées courtes. Notre propre page d’exemples de changelog rassemble des pages qui trouvent cet équilibre.

Comment les gens s’abonnent-ils ?

Donnez-leur les voies qu’ils utilisent déjà : un flux RSS ou JSON pour les développeurs, un email pour ceux qui ne veulent entendre que les choses importantes, et le widget in-app pour tous ceux qui ne feront jamais ni l’un ni l’autre. Demandez ce qu’ils veulent entendre plutôt que de le supposer, car un lecteur qui veut les changements cassants et reçoit des corrections de texte se désabonne des deux.

La voie à ajouter en dernier est celle qui ferme la boucle. Quand une entrée résout ce qu’une personne précise a demandé, dites-le-lui directement plutôt que d’espérer qu’elle lise la page. Chez changeloop, l’entrée est publiée d’un coup sur la page, le flux et le widget, et une personne dont le retour via le widget est devenu l’issue GitHub que la pull request a fermée en est avertie sur cette issue, avec un lien vers l’entrée, et voit l’entrée dans le widget. Le mécanisme est le même que n’importe quel abonnement ; la différence est que le destinataire a déjà demandé. C’est l’argument développé dans fermer la boucle de feedback depuis le changelog.

FAQ

La page de changelog devrait-elle être sur un sous-domaine ou un chemin ? Un chemin sur le site principal par défaut, car il hérite de l’autorité du site et ne nécessite pas d’infrastructure supplémentaire. Un sous-domaine se justifie quand un système différent sert la page.

Combien d’entrées la page devrait-elle montrer à la fois ? Assez pour remplir un écran et pas plus, avec pagination ensuite. Charger deux ans d’historique dans un document est lent et rend l’entrée la plus récente plus difficile à trouver.

Les anciennes entrées devraient-elles jamais être supprimées ? Non. Elles sont citées depuis l’extérieur de votre site et les liens se cassent. Corrigez une entrée sur place avec une note, et gardez l’URL en vie.

Chaque changement doit-il apparaître sur la page ? Seulement ceux qu’un utilisateur pourrait remarquer. Une page qui journalise des refactorisations internes entraîne les lecteurs à survoler, et une page survolée échoue le jour où elle porte quelque chose d’urgent.

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 : Exemples de changelog, Documentation développeurs