Huh

Que fait Huh ?

L'utilisateur n'a pas compris votre dernier message. C'est votre faute, pas la sienne.

/huh est le son qu'une personne émet quand son cerveau s'arrête. Cela signifie qu'une de ces choses s'est produite :

1. Vous avez écrit quelque chose de trop dense pour être lu une fois et compris.
2. Vous avez utilisé des mots du code, pas des mots du produit.
3. Vous avez demandé une décision basée sur des faits que l'utilisateur n'a jamais vus. Les faits ont défilé dans un terminal il y a une heure. Vous les avez lus. L'utilisateur ne les a pas lus.

Règles

Arrêtez le travail. N'exécutez pas d'outils. Ne modifiez pas de fichiers. Ne continuez pas la tâche. Ne commencez pas un nouveau plan. Votre seul travail pendant ce tour est de faire comprendre l'utilisateur et de demander ce dont vous avez besoin.

Ne défendez pas le dernier message. Ne le répétez pas. Ne dites pas « comme je l'ai mentionné ». Ne vous excusez pas plus d'une phrase courte, et seulement si vous devez le faire.

N'ajoutez pas de nouvelles informations. L'utilisateur est déjà surchargé. Donnez moins, pas plus.

Supposez que l'utilisateur n'a rien lu de votre sortie. Il n'a pas lu le code que vous avez écrit. Il n'a pas lu la sortie des outils. Il n'a pas lu le plan d'il y a vingt tours. Il ne peut pas garder chaque détail de chaque tour en tête. C'est normal. Écrivez pour une personne intelligente qui vient d'entrer dans la pièce.

Étape 1 — Trouver le contexte invisible

Regardez votre dernier message. Pour chaque fait, nombre, nom de fichier, erreur ou décision que vous avez mentionné, demandez :

• L'utilisateur a-t-il déjà vu ceci ?
• L'utilisateur a-t-il déjà dit quelque chose à ce sujet ?

Tout ce qui vient d'un résultat d'outil, d'un fichier que vous avez lu, d'un journal, d'une exécution de test, ou de votre propre raisonnement antérieur est invisible sauf si l'utilisateur y a répondu directement. Le silence n'est pas un accord. Un long tour n'est pas une mémoire partagée.

Listez les éléments invisibles. Gardez les trois ou quatre qui comptent pour la décision. Dites d'où vient chaque élément et ce qu'il signifie pour l'utilisateur.

Étape 2 — Reformuler en mots d'utilisateur final

Décrivez le problème, la question ou la réponse comme une personne qui utilise le produit fini le vivrait.

• Pas « le middleware d'authentification retourne 401 lors du rafraîchissement. » → « Les utilisateurs sont déconnectés quand ils rechargent la page. »
• Pas « la migration n'est pas idempotente. » → « Si nous exécutons cela deux fois, cela casse les données. »
• Pas « nous devons décider de la stratégie d'invalidation du cache. » → « Quand quelqu'un change un prix, à quelle vitesse les autres devraient-ils voir le nouveau prix ? »

Si un mot technique est inévitable, utilisez-le une fois et expliquez-le dans la même phrase en mots simples.

Étape 3 — Posez jusqu'à trois questions simples

Demandez seulement ce dont vous avez besoin pour continuer. Moins de questions est mieux. Une seule est souvent suffisante.

Chaque question doit :

• Ne porter que sur une seule chose.
• Proposer deux ou trois choix concrets.
• Dire quel choix vous recommandez, et pourquoi, en une phrase courte.
• Être répondable sans ouvrir un fichier ou lire du code.

Ne posez jamais une question ouverte comme « comment voulez-vous gérer cela ? » Cela repousse votre travail sur l'utilisateur.

Règles de langage

Écrivez en français simplifié, dans le style du français clair et direct.

• Une idée par phrase.
• Vingt mots par phrase, maximum.
• Voix active uniquement. « L'application supprime le fichier », pas « le fichier est supprimé ».
• Temps présent si possible.
• Utilisez le même mot pour la même chose à chaque fois. N'utilisez pas de synonymes pour varier.
• Utilisez des mots courts et courants. Voir la liste de mots ci-dessous.
• Pas d'argot. Pas d'idiomes. Pas de métaphores. Pas de blagues. Pas d'emoji.
• Écrivez un acronyme en entier la première fois que vous l'utilisez.
• Pas de blocs de code, sauf si l'utilisateur doit copier-coller quelque chose.
• Pas de tableaux, sauf si vous comparez exactement deux ou trois options.

Échanges de mots

N'écrivez pas	Écrivez
utiliser à fond, mettre à profit	utiliser
implémenter	construire, ajouter
instancier, initialiser	démarrer, configurer
terminer (processus)	arrêter, terminer
persister	sauvegarder
faire remonter, exposer	montrer
propager	transmettre
déprécier	arrêter d'utiliser
refactoriser	nettoyer, réécrire
point de terminaison, route	adresse web, page
charge utile, objet	donnée, information
régression	une chose qui marchait et qui ne marche plus
cas limite	situation rare
non trivial	difficile
idempotent	sans danger à exécuter plus d'une fois

Format de sortie

Utilisez cette structure exacte. Utilisez ces titres exacts.

**Version courte**
Deux à quatre phrases. Ce qui se passe, en mots d'utilisateur final. Pas de détail.

**Ce que vous n'avez pas vu**
- Un fait. D'où il vient. Pourquoi il compte. (Une ligne chacun, maximum trois ou quatre puces.)

**Ce dont j'ai besoin**
1. Une question. Choix : A ou B. Je suggère A, parce que [une raison courte].
2. (Seulement si nécessaire.)
3. (Seulement si nécessaire.)

Longueur

Deux cents mots au total, maximum. Si cela ne tient pas, vous ne l'avez pas assez simplifié. Coupez le détail, pas la clarté.

Exemple

Mauvais (le message qui a causé le /huh) :

La suite de tests d'intégration échoue sur le chemin de rafraîchissement du jeton parce que l'horloge simulée avance au-delà de la revendication d'expiration du JWT avant que l'intercepteur ne se déclenche. Je peux soit simuler Date.now dans le harnais de test, soit augmenter la tolérance sur le vérificateur. Que préférez-vous étant donné la décision précédente concernant la tolérance au décalage d'horloge ?

Bon (la réponse /huh) :

Version courte Un test échoue. Le test concerne le maintien de la connexion. Le test simule le temps qui avance. Il avance le temps trop loin, donc la connexion expire avant que l'application puisse la renouveler. L'application elle-même est probablement correcte. Le test est erroné.

Ce que vous n'avez pas vu

• L'échec du test s'est produit quand j'ai exécuté les tests il y a quelques minutes. Vous n'avez jamais vu la sortie.
• Plus tôt dans cette session, nous avons choisi d'autoriser une différence de 30 secondes entre les horloges. Ce choix est la raison pour laquelle ce test est proche de la limite.

Ce dont j'ai besoin

1. Voulez-vous que je corrige seulement le test, ou aussi que je rende l'application plus tolérante au temps ? Choix : corriger seulement le test, ou corriger les deux. Je suggère de corriger seulement le test, parce que le comportement de l'application est déjà ce que nous avons convenu.

Quand /huh est déclenché deux fois

Un deuxième /huh signifie que le premier n'a pas fonctionné. Ne vous contentez pas de vous répéter avec des mots plus courts. D'abord, décidez laquelle de ces trois choses a mal tourné.

1. Le langage est toujours trop difficile. Signes : l'utilisateur demande à propos d'un mot que vous avez utilisé, ou répète un terme avec un point d'interrogation.

Correction : écrivez à nouveau avec un indice de lisibilité élevé. Vous ne pouvez pas le mesurer, alors utilisez ces objectifs à la place. Gardez les phrases à environ dix mots. Utilisez des mots d'une ou deux syllabes. Utilisez sujet, puis verbe, puis objet, dans cet ordre, dans chaque phrase. Ne commencez pas une phrase par une proposition.

Changez aussi la forme de la réponse. N'utilisez pas une liste de faits séparés. Écrivez une chaîne d'idées connectée. Chaque phrase doit être liée à la phrase précédente. Le lecteur ne doit jamais avoir à retenir deux idées à la fois.

L'application sauvegarde votre fichier. Elle sauvegarde le fichier dans un dossier. Ce dossier est maintenant plein. Donc la prochaine sauvegarde échoue. C'est l'erreur que vous avez vue.

2. Vous êtes perdu dans les détails. Signes : votre réponse était claire, mais elle portait sur une petite partie, et l'utilisateur ne voit toujours pas pourquoi cela compte.

Correction : nommez d'abord l'objectif supérieur. Dites ce que l'utilisateur a entrepris de construire. Ensuite, dites, en une ou deux phrases, comment cette petite chose bloque cet objectif. Puis posez votre question. Si vous ne pouvez pas relier le détail à l'objectif, c'est votre réponse : le détail ne compte pas, et vous devriez l'abandonner et le dire.

3. L'utilisateur ne se souvient pas comment vous en êtes arrivé là. Signes : le travail a beaucoup dérivé de son point de départ. De nombreux tours ont passé. L'utilisateur demande à propos d'une décision dont il ne se souvient pas avoir prise, ou le sujet actuel n'a rien à voir avec la demande initiale.

Correction : commencez par un court « comment nous en sommes arrivés là ». Utilisez quatre ou cinq étapes, dans l'ordre, en mots simples. Commencez par la chose que l'utilisateur a demandée en premier. Terminez à aujourd'hui.

Vous avez demandé que les utilisateurs se connectent avec leur email. Nous avons construit cela. Ensuite, nous avons découvert que les connexions chutent après une heure. Pour résoudre cela, nous avons ajouté un rafraîchissement de jeton. Le rafraîchissement est ce qui est cassé maintenant.

Ensuite, donnez les choix. Pour chaque choix, dites ce qu'il coûte et ce qu'il apporte. Évaluez chaque choix par rapport à l'objectif original, pas par rapport au problème actuel. Dites clairement si un choix ne sert que la piste secondaire. L'un des choix devrait presque toujours être « arrêter cette branche et revenir en arrière ».

Comment choisir

Si le deuxième /huh de l'utilisateur est venu rapidement et brièvement, supposez 1. Si la conversation est longue et a dérivé, supposez 3. Si aucun des deux ne correspond, supposez 2. Quand vous n'êtes pas sûr entre 2 et 3, utilisez 3. Cela coûte quelques mots de plus et c'est la réparation la plus sûre.

Ne demandez jamais à l'utilisateur lequel des trois c'est. C'est une chose de plus pour lui à comprendre, et comprendre les choses est le problème.

Après que l'utilisateur a répondu

Retournez au travail. Gardez le langage simple pour le reste de la conversation jusqu'à ce que l'utilisateur signale qu'il veut plus de détails.