Règles pour rédiger des tutoriels logiciels

xguru · 2025-01-15T10:41:02+09:00

La plupart des tutoriels logiciels omettent des détails importants ou reposent sur des hypothèses implicites qui ne correspondent pas aux attentes des lecteurs, ce qui les empêche de reproduire le processus En suivant quelques règles simples, il est plus facile qu’on ne le pense de rédiger un excellent tutoriel Règles Écrire pour les débutants Rédiger un titre qui promet un résultat clair Expliquer l’objectif dans l’introduction Montrer le résultat final à l’avance Écrire des extraits de code copiables/collables Utiliser des options longues dans les commandes Séparer les valeurs personnalisables de la logique réutilisable Réduire les efforts du lecteur Écrire de façon à ce que le code reste toujours fonctionnel N’enseigner qu’un seul sujet Faire passer la clarté avant l’esthétique Minimiser les dépendances Indiquer clairement les noms de fichiers Utiliser des titres cohérents et explicites Prouver que la solution fonctionne Lier un exemple complet Écrire pour les débutants L’erreur la plus fréquente dans un tutoriel consiste à expliquer des concepts de niveau débutant avec un vocabulaire d’expert. La plupart des personnes qui recherchent des tutoriels sont débutantes. Elles ne sont peut-être pas débutantes en programmation, mais elles le sont dans le domaine qu’elles veulent apprendre Écrire pour des débutants et éviter autant que possible le jargon d’expert Éviter les termes difficiles et utiliser un langage simple que le lecteur peut comprendre Par exemple, dans un tutoriel React, proposer une formulation comme « créer une page web simple avec React » plutôt que « transpilation JSX » Rédiger un titre qui promet un résultat clair Le titre doit indiquer concrètement ce que le lecteur pourra apprendre grâce au tutoriel Éviter les titres flous ou vagues et décrire clairement le résultat attendu Exemple : "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView" Expliquer l’objectif dans l’introduction Quand un lecteur clique sur un tutoriel, cela signifie qu’il s’intéresse déjà à ce que vous dites. Mais il faut encore le convaincre de continuer à lire Le lecteur se pose deux questions Dois-je m’intéresser à cette technologie ? Si oui, ce tutoriel est-il fait pour moi ? Dans l’introduction, expliquer brièvement pourquoi la technologie est importante et en quoi le tutoriel est utile Fournir des informations utiles qui suscitent l’intérêt du lecteur et éviter les formulations vagues Exemple : un tutoriel Docker doit expliquer clairement le problème que Docker résout et le résultat attendu Montrer le résultat final à l’avance Dès que possible, montrer une démo ou une capture d’écran de ce que le lecteur va créer grâce au tutoriel Montrer le résultat final au début du tutoriel permet de clarifier l’objectif Exemple : fournir une capture d’écran du produit final, de l’interface utilisateur ou un exemple de fonctionnement Écrire des extraits de code copiables/collables Rédiger les exemples de manière à ce que le lecteur puisse facilement copier le code, le coller dans son éditeur ou son terminal, puis l’exécuter Supprimer les éléments inutiles comme le caractère d’invite du terminal $ Utiliser des options non interactives pour simplifier les commandes, et && pour arrêter l’exécution en cas d’échec Utiliser des options longues dans les commandes Dans les commandes, utiliser des options longues plutôt que des options courtes afin qu’elles soient faciles à comprendre, même pour un débutant -r plutôt que --recursive Séparer les valeurs personnalisables de la logique réutilisable Dans le code, séparer clairement les valeurs que l’utilisateur doit modifier de celles qu’il ne doit pas toucher Utiliser des variables d’environnement pour définir les valeurs personnalisées et améliorer la lisibilité du code Réduire les efforts du lecteur Respecter le temps du lecteur afin qu’il apprécie le tutoriel Remplacer les tâches fastidieuses par des extraits de commandes Exemple : résoudre le problème par une commande plutôt qu’en modifiant un fichier manuellement Écrire de façon à ce que le code reste toujours fonctionnel Le code d’exemple doit toujours pouvoir être exécuté et rester fonctionnel à chaque étape intermédiaire Un code erroné ou un exemple non fonctionnel crée de la confusion pour le lecteur N’enseigner qu’un seul sujet Le tutoriel doit être centré sur un seul sujet et ne pas mélanger des technologies sans rapport Par exemple, un tutoriel sur une fonction de recherche ne doit pas ajouter inutilement des technologies d’IA Faire passer la clarté avant l’esthétique Le lecteur ne se soucie pas de savoir si une application de démonstration est jolie Réduire au minimum le CSS et les éléments de design inutiles, et se concentrer sur les concepts essentiels Utiliser un code simple plutôt que des exemples complexes afin de transmettre clairement les concepts Minimiser les dépendances Réduire au minimum les dépendances que le lecteur doit installer afin de rendre le tutoriel plus accessible Indiquer clairement les dépendances indispensables et préciser les versions concernées Indiquer clairement les noms de fichiers Indiquer précisément au lecteur quels fichiers modifier, avec leur chemin et leur contenu Par exemple, au lieu de dire « ajouter une configuration dans le fichier config », fournir le chemin complet du fichier et un extrait de code précis montrant exactement quelle ligne modifier Utiliser des titres cohérents et explicites Utiliser des titres structurés pour permettre au lecteur de parcourir facilement le tutoriel Structurer le tutoriel à l’aide des titres, en veillant à ce qu’ils reflètent une organisation logique Garder un format, un point de vue et un temps cohérents dans les titres Prouver que la solution fonctionne Si le tutoriel explique comment installer un outil ou intégrer plusieurs composants, montrer comment utiliser le résultat Montrer visuellement au lecteur le résultat du fonctionnement des outils installés ou intégrés Par exemple, afficher la page de succès de nginx et expliquer comment la vérifier via l’URL Lier un exemple complet Fournir un lien vers un dépôt contenant tout le code du tutoriel afin que le lecteur puisse vérifier l’ensemble du flux Diviser le code de chaque étape en branches git distinctes pour permettre au lecteur de suivre chaque étape

(refactoringenglish.com)

70 points par xguru 2025-01-15 | 11 commentaires | Partager sur WhatsApp

La plupart des tutoriels logiciels omettent des détails importants ou reposent sur des hypothèses implicites qui ne correspondent pas aux attentes des lecteurs, ce qui les empêche de reproduire le processus
En suivant quelques règles simples, il est plus facile qu’on ne le pense de rédiger un excellent tutoriel

Règles

Écrire pour les débutants
Rédiger un titre qui promet un résultat clair
Expliquer l’objectif dans l’introduction
Montrer le résultat final à l’avance
Écrire des extraits de code copiables/collables
Utiliser des options longues dans les commandes
Séparer les valeurs personnalisables de la logique réutilisable
Réduire les efforts du lecteur
Écrire de façon à ce que le code reste toujours fonctionnel
N’enseigner qu’un seul sujet
Faire passer la clarté avant l’esthétique
Minimiser les dépendances
Indiquer clairement les noms de fichiers
Utiliser des titres cohérents et explicites
Prouver que la solution fonctionne
Lier un exemple complet

Écrire pour les débutants

L’erreur la plus fréquente dans un tutoriel consiste à expliquer des concepts de niveau débutant avec un vocabulaire d’expert. La plupart des personnes qui recherchent des tutoriels sont débutantes.
- Elles ne sont peut-être pas débutantes en programmation, mais elles le sont dans le domaine qu’elles veulent apprendre
Écrire pour des débutants et éviter autant que possible le jargon d’expert
Éviter les termes difficiles et utiliser un langage simple que le lecteur peut comprendre
Par exemple, dans un tutoriel React, proposer une formulation comme « créer une page web simple avec React » plutôt que « transpilation JSX »

Rédiger un titre qui promet un résultat clair

Le titre doit indiquer concrètement ce que le lecteur pourra apprendre grâce au tutoriel
Éviter les titres flous ou vagues et décrire clairement le résultat attendu
- Exemple : "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"

Expliquer l’objectif dans l’introduction

Quand un lecteur clique sur un tutoriel, cela signifie qu’il s’intéresse déjà à ce que vous dites. Mais il faut encore le convaincre de continuer à lire
Le lecteur se pose deux questions
- Dois-je m’intéresser à cette technologie ?
- Si oui, ce tutoriel est-il fait pour moi ?
Dans l’introduction, expliquer brièvement pourquoi la technologie est importante et en quoi le tutoriel est utile
Fournir des informations utiles qui suscitent l’intérêt du lecteur et éviter les formulations vagues
- Exemple : un tutoriel Docker doit expliquer clairement le problème que Docker résout et le résultat attendu

Montrer le résultat final à l’avance

Dès que possible, montrer une démo ou une capture d’écran de ce que le lecteur va créer grâce au tutoriel
- Montrer le résultat final au début du tutoriel permet de clarifier l’objectif
Exemple : fournir une capture d’écran du produit final, de l’interface utilisateur ou un exemple de fonctionnement

Écrire des extraits de code copiables/collables

Rédiger les exemples de manière à ce que le lecteur puisse facilement copier le code, le coller dans son éditeur ou son terminal, puis l’exécuter
Supprimer les éléments inutiles comme le caractère d’invite du terminal $
Utiliser des options non interactives pour simplifier les commandes, et && pour arrêter l’exécution en cas d’échec

Utiliser des options longues dans les commandes

Dans les commandes, utiliser des options longues plutôt que des options courtes afin qu’elles soient faciles à comprendre, même pour un débutant
- -r plutôt que --recursive

Séparer les valeurs personnalisables de la logique réutilisable

Dans le code, séparer clairement les valeurs que l’utilisateur doit modifier de celles qu’il ne doit pas toucher
Utiliser des variables d’environnement pour définir les valeurs personnalisées et améliorer la lisibilité du code

Réduire les efforts du lecteur

Respecter le temps du lecteur afin qu’il apprécie le tutoriel
Remplacer les tâches fastidieuses par des extraits de commandes
- Exemple : résoudre le problème par une commande plutôt qu’en modifiant un fichier manuellement

Écrire de façon à ce que le code reste toujours fonctionnel

Le code d’exemple doit toujours pouvoir être exécuté et rester fonctionnel à chaque étape intermédiaire
Un code erroné ou un exemple non fonctionnel crée de la confusion pour le lecteur

N’enseigner qu’un seul sujet

Le tutoriel doit être centré sur un seul sujet et ne pas mélanger des technologies sans rapport
Par exemple, un tutoriel sur une fonction de recherche ne doit pas ajouter inutilement des technologies d’IA

Faire passer la clarté avant l’esthétique

Le lecteur ne se soucie pas de savoir si une application de démonstration est jolie
Réduire au minimum le CSS et les éléments de design inutiles, et se concentrer sur les concepts essentiels
Utiliser un code simple plutôt que des exemples complexes afin de transmettre clairement les concepts

Minimiser les dépendances

Réduire au minimum les dépendances que le lecteur doit installer afin de rendre le tutoriel plus accessible
Indiquer clairement les dépendances indispensables et préciser les versions concernées

Indiquer clairement les noms de fichiers

Indiquer précisément au lecteur quels fichiers modifier, avec leur chemin et leur contenu
Par exemple, au lieu de dire « ajouter une configuration dans le fichier config », fournir le chemin complet du fichier et un extrait de code précis montrant exactement quelle ligne modifier

Utiliser des titres cohérents et explicites

Utiliser des titres structurés pour permettre au lecteur de parcourir facilement le tutoriel
Structurer le tutoriel à l’aide des titres, en veillant à ce qu’ils reflètent une organisation logique
Garder un format, un point de vue et un temps cohérents dans les titres

Prouver que la solution fonctionne

Si le tutoriel explique comment installer un outil ou intégrer plusieurs composants, montrer comment utiliser le résultat
- Montrer visuellement au lecteur le résultat du fonctionnement des outils installés ou intégrés
Par exemple, afficher la page de succès de nginx et expliquer comment la vérifier via l’URL

Lier un exemple complet

Fournir un lien vers un dépôt contenant tout le code du tutoriel afin que le lecteur puisse vérifier l’ensemble du flux
Diviser le code de chaque étape en branches git distinctes pour permettre au lecteur de suivre chaque étape

11 commentaires

godogi7 2025-02-12

À titre de référence

wedding 2025-01-16

À surveiller !

ilikeall 2025-01-16

C'est un bon article.

halfenif 2025-01-16

J’ai récemment suivi le tutoriel de dagster. Je me suis dit que c’était vraiment bien fait.

https://courses.dagster.io/

aer0700 2025-01-16

J’ai parcouru le tutoriel Dagster, et il est vraiment excellent.
Le tutoriel Django est riche en contenu, mais il est trop long à mon goût. J’aimerais qu’il soit davantage découpé.

savvykang 2025-01-16

Il y a aussi Django comme exemple de tutoriel bien conçu : https://docs.djangoproject.com/en/5.1/intro/tutorial01/

jhj0517 2025-01-16

Utiliser un langage simple & montrer le résultat final en premier.

aer0700 2025-01-15

Au lieu de montrer les bases ennuyeuses d’utilisation d’un framework,
on voit parfois des tutoriels qui veulent surtout montrer à quel point ce framework est génial.
Quand j’ouvre le Get started et que le tutoriel censé expliquer les bases fait 10 pages, je déteste ça.

beenzinozino 2025-01-16

Vous êtes tous impressionnants...

savvykang 2025-01-15

https://tanstack.com/table/latest/docs/introduction

nono9633 2025-01-15

https://github.com/tmux/tmux/wiki/Getting-Started