Changelogs vs Notes de Version : Une comparaison approfondie

Qu'est-ce qu'un changelog ?

Un changelog - ou journal des modifications - est un document détaillé qui fournit une vue d'ensemble de tous les changements, mises à jour, améliorations et corrections apportés à un produit logiciel au fil du temps.

Il s'agit généralement d'un ordre chronologique inversé, qui présente les modifications les plus récentes en haut de la page et les versions antérieures du produit vers la fin de la page.

Cela pourrait ressembler à ceci :

Ou encore ceci :

Il vous appartient d'annoncer (ou non) vos fonctionnalités à venir ou les projets sur lesquels votre équipe de développeurs travaille actuellement. En fonction de vos produits/services et de votre base d'utilisateurs, le type de système d'étiquetage et de catégorisation que vous utilisez pour vos entrées dans le changelog peut également changer.

Indépendamment de ces différences stratégiques, un bon changelog doit toujours être clair et organisé. Il doit permettre à votre public de naviguer facilement pour trouver les informations pertinentes. Mais nous discuterons de ce qui fait un bon changelog dans les sections suivantes, alors ne vous inquiétez pas pour l'instant.

Qu'est-ce qu'une note de version ?

À l'instar d'un changelog, une note de version est un document qui fournit des informations sur les nouvelles fonctionnalités, les améliorations du produit et les mises à jour majeures.

Cependant, contrairement aux entrées du journal des modifications qui incluent même les plus petites corrections de bogues, les notes de version n'incluent généralement que les changements significatifs et les améliorations des fonctionnalités majeures qui sont susceptibles d'avoir un impact sur l'expérience de l'utilisateur.

Les notes de version sont également plus conviviales et plus faciles à lire car elles sont dépourvues de jargon technique. Elles sont également accompagnées d'éléments visuels, tels que des vidéos ou des captures d'écran de l'interface utilisateur.

Les notes de version offrent une plus grande liberté en termes de structure et de conception. Elles diffèrent donc davantage les unes des autres par rapport aux structures et conceptions relativement similaires des changelogs.

Voici toutefois quelques exemples :

Comme vous pouvez le constater, une note de version n'est pas nécessairement une communication à sens unique dans laquelle vous partagez vos nouvelles et vos mises à jour tandis que vos clients se contentent d'écouter (ou de lire). Vous pouvez également en faire une expérience interactive en offrant à vos clients la possibilité de donner leur avis ou de réagir rapidement.

Comprendre les différences entre les changelogs et les notes de version

Bien que les notes de version et les changelogs soient des supports permettant aux équipes de produits d'annoncer des changements ou des améliorations, ils diffèrent considérablement dans leur structure, leur utilisation de la langue et plusieurs autres aspects.

Voyons comment 🔎

Public cible

Les changelogs et les notes de version s'adressent à des publics différents. Alors que les changelogs sont lus principalement par les développeurs et les utilisateurs techniques, les notes de version s'adressent à un large public, tel que les utilisateurs non techniques et les parties prenantes.

Toutes les autres différences entre les notes de version et les changelogs découlent en fait de cette différence principale.

Niveau de détail

Les changelogs sont essentiellement des listes complètes de toutes les modifications apportées depuis la première introduction du produit jusqu'à aujourd'hui, ce qui signifie qu'ils incluent même les plus petits correctifs et améliorations.

Les notes de version, quant à elles, mettent l'accent sur les fonctionnalités, les améliorations et les introductions clés qui sont pertinentes pour l'expérience globale de l'utilisateur. Comme il s'agit d'une publication destinée à un public non technique, il n'est pas nécessaire d'inclure les petites corrections de bogues si elles ne sont pas radicalement importantes ou même perceptibles pour l'utilisateur moyen.

Ton et style

Si les entrées du changelog ont tendance à être plus détaillées en termes de changements, elles ne sont pas nécessairement plus explicites ou faciles à comprendre.

Les changelogs ne fournissent généralement pas d'instructions approfondies ou de cas d'utilisation pour les nouvelles fonctionnalités. Ils décrivent la nature du changement, mais ne sont pas très détaillés et utilisent un langage plus technique, car ils sont destinés aux développeurs.

En revanche, les notes de version ont tendance à être plus explicatives et instructives. Elles utilisent un langage plus clair, plus concis et plus convivial, et incluent souvent des exemples de cas d'utilisation, des avantages et des explications supplémentaires.

L'objectif d'un changelog est d'informer un développeur ou un utilisateur technique d'une modification, sans nécessairement l'inciter à agir.

En revanche, une note de version ne se contente pas d'informer les utilisateurs d'un changement, mais les encourage également à agir, par exemple en essayant une nouvelle fonctionnalité. C'est pourquoi les notes de version comprennent souvent des déclencheurs de motivation tels que des propositions de valeur et des instructions.

Format et structure

Les listes de modifications sont souvent présentées dans l'ordre chronologique inverse. Les notes de version, quant à elles, sont structurées de manière à mettre en évidence les mises à jour les plus importantes en premier.

Ils sont souvent classés par nouvelles fonctionnalités, améliorations et corrections de bogues pour une meilleure lisibilité. Ils contiennent également un grand nombre de détails techniques tels que les numéros de version, les numéros d'édition, les dates de publication, les extraits de code, etc.

Bien que tous ces éléments puissent également être disponibles dans une note de version, la plupart du temps, ils ne sont pas inclus afin de ne pas submerger les utilisateurs avec trop de détails techniques et sont conservés uniquement dans les changelogs.

Utilisation de visuels

Une autre différence importante entre les changelogs et les notes de version est l'utilisation de visuels, tels que des captures d'écran de l'interface utilisateur ou des vidéos explicatives et des visites de produits.

Bien que certaines entreprises, comme Mixpanel, intègrent des visuels -voire des vidéos- dans leurs changelogs, il n'est pas très courant d'ajouter des GIF, des captures d'écran ou des vidéos de visite de produits aux entrées du changelog (mais nous voyons beaucoup d'extraits de code si vous voulez les compter comme des visuels, aussi).

Toutefois, comme les notes de version s'adressent à des utilisateurs non techniques, elles ont tendance à intégrer de nombreux éléments visuels pour aider les apprenants visuels à comprendre l'aspect et le fonctionnement de la nouvelle fonctionnalité.

Les meilleurs cas d'utilisation des changelogs et des notes de version (+ exemples)

Toutes ces différences entre les changelogs et les notes de version ne signifient pas que l'un est parfait et l'autre terrible. Au contraire, elles les rendent adaptées à des cas d'utilisation différents, qui peuvent être énumérés comme suit : 👇🏻

Les changelogs sont utiles pour :

• Suivi de l'historique du projet et des modifications du code.
• Fournir des informations détaillées aux développeurs et aux équipes techniques.
• Créer un point de référence pour les équipes internes, telles que les équipes d'assistance.
• Maintenir la transparence et informer les parties prenantes.  

Les notes de version sont utiles :

• Annoncer les nouvelles fonctionnalités et les mises à jour au grand public.
• Mettre en évidence les cas d'utilisation et les propositions de valeur pour les utilisateurs finaux.
• Encourager les utilisateurs à essayer une nouvelle fonctionnalité ou une nouvelle intégration.
• Créer un point de référence pour les équipes internes, telles que les équipes chargées de la réussite des clients, des ventes et du marketing.
• Communiquer avec les utilisateurs finaux et recueillir leurs réactions après la sortie des versions.

Voyons quelques exemples concrets de ces cas d'utilisation 👀

#1 CoScreen explique pourquoi les utilisateurs devraient essayer leur nouvelle fonctionnalité

CoScreen est un outil de partage d'écran collaboratif spécialement conçu pour les équipes de développement de produits et les équipes d'ingénieurs.

Voici un communiqué de presse de CoScreen :

Étant donné que CoScreen est un outil SaaS destiné aux développeurs, même leurs notes de version contiennent du jargon technique. Mais il s'agit toujours d'une note de version et non d'une entrée du changelog.

Nous savons comment ?

En effet, il ne s'agit pas simplement d'annoncer "Hé, nous avons lancé CoTerm Beta !" et de passer à d'autres modifications du produit. Au lieu de cela, il fournit des motivations aux utilisateurs pour les encourager à essayer la fonctionnalité.

⚠️ Ainsi, même si votre clientèle est composée de développeurs et de codeurs capables de comprendre les entrées de votre changelog, vous avez toujours besoin de notes de version en plus du changelog pour communiquer vos propositions de valeur à vos utilisateurs.

2- Notion liste (petite ou grande) tous les changements et mises à jour

Notion est l'un des outils de prise de notes et d'espace de travail les plus populaires.

Et voici à quoi ressemble le changelog :

Il existe des journaux de modifications conçus spécifiquement pour les annonces de produits, avec des étiquettes, des catégories et des entrées distinctes pour chaque mise à jour. D'autre part, il existe des journaux de modifications conçus pour conserver un historique complet des produits au fil du temps.

Il s'agit d'un exemple du deuxième type de changelog.

Notion offre un rapport très détaillé et complet de ce que son équipe de développeurs a accompli, documentant chaque changement, quelle qu'en soit l'importance.

Ont-ils apporté des précisions à la documentation du produit ?

Il renvoie au changelog.

3- Slack assure la transparence en mettant en évidence les mises à jour importantes.

Vous connaissez Slack. Et je sais que vous connaissez Slack.

Sautons donc l'introduction et passons au journal des changements de Slack 🦘

Le journal des modifications de Slack fonctionne de la même manière que celui de Notion, listant les dernières mises à jour en premier et les plus anciennes plus bas dans la page.

Mais ce que Slack fait différemment, c'est qu'il place les mises à jour importantes comme les changements de politique ou les dépréciations tout en haut, dans une section appelée "Mises à jour importantes". Ainsi, même si quelque chose a été annoncé en mars ou en avril, si c'est toujours pertinent, vous le verrez tout de suite lorsque vous ouvrirez le changelog.

Comme ceci :

4- Miro s'attaque d'abord aux problèmes des clients, puis leur propose des solutions

Miro est un outil de collaboration numérique et un tableau blanc qui permet de collaborer sur des dessins, des présentations, des cartes mentales et des feuilles de route.

Voici un extrait de l'une de ses notes de version mensuelles :

Ce que Miro fait ici, c'est parler directement aux besoins insatisfaits d'un certain segment d'utilisateurs : les grandes entreprises. Après s'être attaqué à leurs points faibles, il offre une solution à leurs problèmes et présente sa proposition de valeur.

Il en va de même pour la deuxième note de fonctionnalité. Miro montre qu'il comprend ses clients et leurs besoins, et son équipe de développeurs s'efforce de garantir leur satisfaction et leur bonheur.

5- UserGuiding recueille les commentaires directement sur sa page de mise à jour des produits

UserGuiding est un outil d'adoption de produits tout-en-un qui permet aux équipes de créer des flux interactifs in-app, des centres de ressources, des enquêtes clients et des pages de mises à jour du produit.

Voici à quoi ressemble la page de mises à jour des produits :

• Étiquetage ✅
• Microcopie amicale ✅
• Communication bidirectionnelle ✅

UserGuiding ne se contente pas d'utiliser sa page de mise à jour des produits pour publier des notes de version ; elle s'en sert également pour recueillir les commentaires (écrits ou réactions) de ses utilisateurs. C'est l'occasion de tâter le terrain et de s'engager directement auprès de ses utilisateurs.

Il peut être difficile de déterminer quel commentaire d'utilisateur correspond à une mise à jour ou à une fonctionnalité spécifique, en particulier lorsque les entreprises publient plusieurs changements sur une courte période, comme les mises à jour mensuelles.

Toutefois, avec ce système, si les entreprises peuvent attribuer les commentaires des utilisateurs à des mises à jour spécifiques, les utilisateurs peuvent soumettre des demandes de fonctionnalités ou laisser des commentaires, même de manière anonyme !

👉🏻 Essayez-le vous-même 👈🏻

Bonnes pratiques pour les changelogs

Maintenant que nous avons vu quelques exemples et que nous nous sommes familiarisés avec les changelogs, discutons des pratiques qui transforment les changelogs médiocres en changelogs remarquables.

Créer un système (et s'y tenir)

Un changelog n'est pas une poubelle de mises à jour du produit.

Que vous publiiez les modifications et améliorations apportées à vos produits sous la forme d'entrées distinctes ou d'un document unique, vous avez besoin d'un système.

Voici quelques suggestions :

• Utilisez des étiquettes et des balises pour catégoriser vos entrées (nouvelles fonctionnalités, corrections de bugs, améliorations de l'interface utilisateur, modifications de l'API, etc.)
• Mettre en place des fonctionnalités de recherche et de filtrage
• Créez un modèle prêt à remplir pour les numéros de version, les numéros de ticket, les numéros de problème, les auteurs, les plans concernés, la date de publication, etc.
• Mettre en évidence les mises à jour importantes par une mise en forme telle que des caractères gras ou un code couleur, ou au début du document d'entrée/de journal des modifications.
• Archiver les anciennes versions

Assurer la clarté

Les changelogs servent de documentation technique destinée principalement aux développeurs et aux utilisateurs techniques. S'il n'est pas nécessaire d'expliquer en détail chaque terme technique, il est en revanche essentiel d'utiliser un langage technique précis et de fournir des détails spécifiques.

Par exemple, lors de l'introduction d'une mise à jour majeure du schéma d'une base de données, il convient d'inclure des instructions claires sur les modifications du schéma, les étapes de migration et tout impact potentiel sur les structures de données existantes ; ou lors de la mise à jour d'une API, il est utile d'inclure des instructions détaillées sur sa mise en œuvre.

Vous pouvez expliquer ces détails dans des zones de texte déroulantes pour que votre changelog soit organisé et facile à parcourir.

Si vous ne pouvez pas faire tenir toutes les instructions et explications dans une zone de texte déroulante (ou si vous le pouvez, mais que cela serait inefficace), vous pouvez créer des guides pratiques distincts dans votre base de connaissances ou vos articles d'aide et les lier à votre changelog.

Vous pouvez également intégrer des éléments visuels et des extraits de code.

Utiliser des intégrations de contrôle de version

Si vous ne souhaitez pas travailler sur un modèle de changelog détaillé - ou utiliser un outil de changelog tiers - mais que vous souhaitez tout de même communiquer les changements techniques et les améliorations de fonctionnalités aux autres développeurs, vous pouvez automatiser votre changelog en le liant aux commits Git.

Lorsque vous apportez des modifications à votre base de code (correction de bogues, ajout de nouvelles fonctionnalités ou amélioration de fonctionnalités existantes), les messages de validation alimentent automatiquement votre journal des modifications et documentent chaque mise à jour en temps réel.

Cette intégration ne fournit pas d'explication ou de description supplémentaire, autre que les changements eux-mêmes.

Vous devez donc toujours les écrire si vous voulez que votre changelog soit utile. Cependant, il est toujours utile, car vous n'avez pas besoin de revenir en arrière et de lister manuellement tous les changements que votre équipe a fait pour ce jour/semaine/mois/trimestre.

C'est donc un bon point de départ, disons.

Bonnes pratiques pour les notes de version

Voici ce que vous pouvez faire pour améliorer vos notes de version 👇🏻

Personnaliser le contenu

Les notes de version contiennent peu ou pas de jargon technique (sauf si vos clients sont uniquement des développeurs, comme c'est le cas de CoScreen). Cependant, les utilisateurs non techniques ne sont pas tous les mêmes. Les responsables de produits, les vendeurs et les responsables du marketing parlent tous un langage différent. Par conséquent, en fonction de votre propre base d'utilisateurs, adaptez votre contenu et votre langage.

Mettre en évidence la proposition de valeur

N'oubliez pas que vous ne vous contentez pas de communiquer sur votre nouvelle fonctionnalité ; vous répondez à un besoin de l'utilisateur et proposez une solution. Il est donc important que vous parliez le même langage que vos utilisateurs lorsque vous rédigez vos notes de version - non seulement d'un point de vue technique, mais aussi en termes de besoins et d'attentes.

Tout comme vous devez éviter un langage trop technique, vous devez également éviter un ton trop commercial. Optez pour un langage simple. Il ne s'agit pas d'un document exclusivement technique, ni d'un argumentaire de vente, alors trouvez un juste milieu.

Dans une note de version, vous pouvez inclure

• Une brève description des nouvelles fonctionnalités
• Cas d'utilisation/ avantages
• Besoins non satisfaits des clients (qui seront satisfaits grâce à ces nouvelles fonctionnalités)

Gardez-le digeste

En fonction de votre stratégie produit, vous pouvez publier des notes de version mensuellement, trimestriellement ou à chaque fois que vous publiez une nouvelle mise à jour. La longueur de vos notes de version peut varier en fonction du calendrier et de la complexité de vos nouvelles fonctionnalités. Toutefois, elles doivent être aussi brèves et faciles à comprendre - et à lire - que possible.

Vous devez également élaborer des stratégies de mise en forme pour éviter d'angoisser vos utilisateurs, en particulier si vous prévoyez de publier de longues notes de version.

Vous pouvez :

• Utilisez des titres, des résumés, des puces et des émojis.
• Incorporer des captures d'écran et des vidéos de visite du produit pour les fonctionnalités complexes.
• Utilisez des liens vers des articles d'aide ou des guides pratiques pour obtenir des détails techniques.

Principaux enseignements

• Les notes de version offrent un historique complet pour les utilisateurs techniques, tandis que les notes de version fournissent un résumé accessible des mises à jour pour une base d'utilisateurs plus large.
• Ces deux documents sont essentiels pour maintenir la transparence, assurer une communication efficace et améliorer l'expérience globale des utilisateurs.
• Les deux sont des points de référence précieux pour les équipes internes. Les changelogs, qui mettent l'accent sur les corrections de bogues et les mises en œuvre techniques, servent de points de référence pour des équipes telles que le service clientèle et le service après-vente. Les notes de version, avec leurs explications détaillées et leurs propositions de valeur, sont des points de référence pour des équipes telles que les ventes et le marketing.

Les listes de modifications utilisent un langage technique et sont généralement structurées sous forme de listes concises avec peu ou pas d'explications supplémentaires. Les notes de version utilisent un langage narratif et mettent en évidence les changements significatifs, leurs avantages pour l'utilisateur et les cas d'utilisation avec des explications et des exemples clairs et détaillés.