Concevoir des outils pour développeurs qui ne vous punissent pas

Les outils puissants se font une réputation d'hostilité, et le raisonnement populaire veut que, si une chose est difficile à utiliser, c'est qu'elle est sérieuse. C'est à l'envers. Les outils punitifs ne filtrent pas la compétence, ils filtrent la tolérance.

Le mensonge selon lequel difficile veut dire puissant

Quelque part en chemin, « outil d'expert » est devenu synonyme de « vous vous en sortirez ou pas ». Des options cryptiques. Des messages d'erreur qui nomment un problème sans nommer de remède. Une documentation qui suppose que vous connaissez déjà la réponse à la question que vous lui posez.

Rien de cela n'est de la puissance. C'est de la friction que personne n'a pris la peine d'éliminer à la conception. Un outil peut être profond et lisible à la fois : la profondeur tient à ce qu'il sait faire, la lisibilité à la façon dont il vous dit ce qu'il fait. Ce sont deux axes distincts, et la plupart des outils qui se vantent du premier négligent discrètement le second.

L'accessibilité dans les outils pour développeurs ne consiste pas à supprimer le grand bain. Elle consiste à ne pas obliger les gens à deviner où sont les marches.

L'abstraction qui porte, et celle qui piège

Il y a une différence entre une abstraction qui vous porte et une qui vous piège. La mauvaise cache si bien le système sous-jacent que, dès que vous quittez le chemin balisé, vous vous retrouvez sans issue, sans aucun modèle de ce qui se passe réellement. La bonne vous donne une surface de travail et garde le système réel accessible.

Le test tient en une phrase : pouvez-vous reproduire à la main tout ce que l'abstraction fait pour vous ? Si la réponse est non, elle cache plutôt qu'elle n'aide, et le jour où elle vous lâche, vous n'aurez aucun terrain où vous tenir.

Trois engagements découlent de ce test, et ce sont ceux auxquels nos propres outils sont tenus :

• Le chemin guidé est le réglage par défaut, jamais le plafond.
• Chaque action générée peut être affichée sous la forme de la commande qu'elle représente.
• Rien de ce que fait l'interface n'est quelque chose que vous ne pourriez pas faire vous-même.

Le troisième a une vraie portée. Il exclut le raccourci pratique où un outil va chercher une API privée ou un fichier d'état caché pour qu'un parcours paraisse fluide, car c'est précisément ce parcours qui vous laisse en plan quand il casse.

La divulgation progressive comme principe premier

La plupart des interfaces placent toutes les options devant vous en même temps et appellent cela de la puissance. Ce n'est pas de la puissance, c'est du bruit. La divulgation progressive signifie que le cas courant est immédiat et que la longue traîne est à une étape délibérée, jamais supprimée.

En pratique, un formulaire de déploiement s'ouvre avec trois champs plutôt que trente, et le panneau avancé (contrôles de santé personnalisés, stratégie de déploiement, limites de ressources) se trouve derrière une bascule explicite : accessible dès que vous en avez besoin, documenté là où il se trouve plutôt que dans un manuel à part qu'il faut aller chercher.

Le même principe se décline jusqu'à une simple commande. Les valeurs par défaut gèrent le cas courant et les options gèrent le reste, de sorte que vous ne payez le coût de la seconde ligne que lorsque vous en avez besoin.

# le cas courant : aucune cérémonie, des valeurs par défaut déjà choisies pour vous
$ deploy

# la même commande, avec toute la longue traîne rendue explicite
$ deploy --strategy=canary --health-timeout=90s --max-surge=2

deploy n'est ici qu'un substitut de l'outil auquel vous voulez appliquer cette exigence. C'est la forme de l'argument qui compte, pas le binaire.

Les valeurs par défaut sont des opinions que l'on livre

Une valeur par défaut est une opinion que l'on livre à tous ceux qui ne la remplacent pas. La traiter comme un détail, quelle que soit la valeur d'initialisation que l'analyseur de configuration a prise, c'est ainsi qu'un outil finit techniquement configurable et pratiquement inutilisable.

La façon de la choisir est de la choisir comme pour un collègue attentif : l'option sûre, réversible et adaptée au cas courant. Un déploiement se fait par défaut de façon progressive plutôt que d'un coup. Une opération destructrice s'exécute par défaut en simulation. Un délai d'expiration est par défaut une valeur qui résiste à un réseau lent au lieu d'échouer au premier accroc.

De bonnes valeurs par défaut signifient que le chemin le plus court est aussi un chemin raisonnable. Personne ne devrait avoir à lire le manuel pour éviter de se tirer une balle dans le pied.

Les messages d'erreur sont la vraie documentation

Personne ne lit la documentation quand tout fonctionne. On lit votre message d'erreur quand quelque chose casse, ce qui en fait le texte le plus lu que votre outil produira jamais. Traitez-le comme tel.

Une bonne erreur répond à trois questions : ce qui s'est passé, pourquoi, et quoi faire ensuite. Une erreur cryptique répond à la première et vous abandonne sur les deux autres.

# cryptique : nomme un symptôme, laisse le lecteur en plan
Error: ECONNREFUSED 127.0.0.1:5432

# utile : nomme la cause, donne la commande suivante, renvoie au contexte
Error: could not connect to the database at 127.0.0.1:5432.
  The postgres service for this project is not running.
  Start it:   docker compose up -d postgres
  Check logs: docker compose logs postgres

Même défaillance sous-jacente. L'une vous laisse traduire un code d'erreur TCP en action, l'autre vous donne l'action. Écrire la seconde version coûte quelques minutes, une fois. La première est payée par chaque utilisateur, chaque fois qu'il tombe dessus, pour toujours.

La règle à laquelle tout message est tenu :

• Nommer la cause, pas seulement le symptôme.
• Donner une étape suivante concrète, idéalement une commande exécutable telle qu'elle est affichée.
• Renvoyer vers le contexte pertinent, pas vers la page d'accueil.
• Ne jamais reprocher à l'utilisateur un état que l'outil lui a permis d'atteindre.

Où cela mène

Accessible ne veut pas dire simple, et puissant ne veut pas dire hostile. Ils n'ont jamais été opposés. Nous nous sommes simplement habitués à des outils qui traitaient la friction comme une fonctionnalité et appelaient experts les survivants.

C'est la norme à laquelle le travail sur les systèmes est tenu ici, y compris le système d'exploitation, qui est en développement et n'a rien à télécharger. Publier la norme avant le logiciel est délibéré : un engagement écrit en public est bien plus facile à contester, et bien plus difficile à abandonner discrètement, qu'un produit déjà livré.