Écrire une documentation que les développeurs lisent vraiment

La plupart des documentations sont écrites une fois, rarement lues, et inspirent un peu moins confiance chaque mois. Nous avons reconstruit la nôtre et, chemin faisant, rassemblé les habitudes qui font qu’une page est lue jusqu’au bout.

Commencer par quelque chose qui s’exécute

Les développeurs arrivent avec une tâche, pas par curiosité. La première chose sur la page doit être le plus petit exemple qui accomplit la tâche, prêt à copier.

curl https://api.example.com/v1/health \
  -H "Authorization: Bearer $API_KEY"

Expliquez-le ensuite. Un paragraphe de contexte avant le premier extrait de code, c’est là que les lecteurs s’en vont.

Garder des pages courtes et à objectif unique

Une page qui répond à une seule question peut être retrouvée, citée et tenue à jour. Une page qui en traite six devient un mur que personne ne maintient.

Un bon test de longueur

Si la page a besoin d’une table des matières pour être navigable, elle gagnerait probablement à devenir deux pages.

Écrire des exemples avec des valeurs réelles

foo et bar n’apprennent rien sur le contenu d’un champ. Utilisez un identifiant de poste plausible, un vrai format de date, un corps d’erreur réaliste. Les lecteurs apprennent la forme de vos données davantage grâce aux exemples qu’avec le schéma.

Montrer les cas d’échec

Chaque page d’API devrait inclure au moins une réponse d’erreur et ce qu’il faut faire face à elle. Les tickets de support viennent surtout de personnes qui empruntent le chemin des erreurs, que la documentation ne montrait jamais.

Rendre la recherche tolérante aux fautes de frappe et aux synonymes

Les gens cherchent ce qu’ils veulent faire, pas le nom que vous avez choisi. Ils tapent « login » quand votre page dit « authentication ». Ajoutez des alias dans le frontmatter des pages et vérifiez chaque mois dans vos journaux de recherche les requêtes sans résultat : chacune correspond à une page manquante ou à un synonyme manquant.

title: Authentication
aliases:
  - login
  - api key
  - sign in

Garder la documentation près du code

Une documentation qui vit dans le même dépôt que le code est mise à jour dans la même pull request. C’est l’idée derrière DocsFlowy, que nous sommes en train de construire : l’orienter vers le markdown d’un dépôt et en publier un site interrogeable. Nous en dirons plus quand il y aura quelque chose à essayer.

Une courte liste de contrôle

• Le premier écran contient-il quelque chose de copiable ?
• La page a-t-elle un objectif clair et unique ?
• Les valeurs d’exemple sont-elles réalistes ?
• Le cas d’erreur est-il montré ?
• Peut-on la trouver en cherchant le mot qu’emploierait un nouvel arrivant ?