Des vidéos de documentation d’API que les développeurs regardent vraiment

Une référence d’API écrite est précise, complète — et presque impossible à utiliser comme point de départ. Le développeur qui arrive sur votre liste d’endpoints comprend chaque champ et n’a pourtant aucune idée de ce à quoi ressemblent les cinq premières minutes avec votre API.

C’est exactement ce vide que comble une vidéo courte. Pas un remplacement de la référence : son complément. Trois minutes montrant une vraie clé, une vraie requête et une vraie réponse répondent à la question que la doc ne peut pas traiter : est-ce que ça marche comme je le crois ?

Voici comment enregistrer ces vidéos pour qu’elles restent utiles.

Choisir ce qui mérite une vidéo

La vidéo coûte cher à maintenir. Investissez-la là où le texte est le plus faible :

• Le premier appel réussi : du terminal vide à la réponse 200. C’est la vidéo la plus utile que vous puissiez produire
• Les flux d’authentification : redirections OAuth, échange de jeton, logique de rafraîchissement sont des séquences. Et la vidéo est faite pour les séquences
• Les workflows en plusieurs étapes : créer une ressource, interroger son statut, récupérer le résultat. La référence les présente comme trois endpoints sans lien
• Webhooks et callbacks : deux systèmes qui se parlent, c’est très difficile à décrire en prose
• Les erreurs fréquentes : une vidéo montrant un 401 et sa correction évite plus de tickets qu’un paragraphe sur le sujet

Ce qui ne mérite pas de vidéo : les paramètres d’un endpoint, les valeurs d’énumération, les limites de débit. Cela appartient au texte, où l’on peut chercher, copier et corriger en quelques secondes.

Préparer une sandbox d’enregistrement

N’enregistrez jamais en production avec une vraie clé. Montez un environnement dédié avant d’appuyer sur Enregistrer.

• Un compte sandbox jetable, avec des clés que vous ferez tourner juste après
• Des données réalistes : test_user_1 et "foo" donnent une impression de faux. Des noms, montants et horodatages plausibles inspirent confiance
• Un format de clé à durée de vie courte si votre API en propose : une image de jeton exposée devient alors inoffensive
• Vérifiez votre environnement shell : la sortie d’env et l’historique ont divulgué plus d’identifiants que n’importe quel extrait de code
• Préchauffez caches et dépendances pour ne pas filmer une installation
• Coupez les notifications — un aperçu Slack dans une vidéo publiée est un incident bien réel

Même en sandbox, considérez chaque image comme publique. Quelqu’un mettra en pause.

Choisir la bonne configuration de capture

Une démo d’API mobilise en général deux ou trois surfaces : un terminal, un éditeur, un client API comme Postman ou Insomnia, parfois un navigateur pour le tableau de bord.

• Une capture de fenêtre par surface garde le cadrage serré et masque le bureau
• Si vous devez changer d’application, disposez-les côte à côte à l’avance et capturez une zone qui couvre les deux. L’alt-tab à l’écran désoriente
• 30 ips suffisent pour du contenu textuel, et un débit d’images plus bas laisse du bitrate pour des caractères nets
• Enregistrez en résolution native — c’est l’agrandissement après coup qui crée le flou
• Passez les polices à 18–24 pt dans le terminal et l’éditeur. Ce qui paraît absurde sur votre écran est juste à l’image

Structurer chaque clip de la même façon

C’est la régularité qui transforme une collection de captures en documentation. Une structure en quatre temps qui fonctionne :

1. Annoncer l’objectif en une phrase : « On va créer un client et le débiter. »
2. Montrer l’authentification : même si ce n’est qu’un en-tête. Il faut voir où va la clé
3. Construire la requête en direct : tapez-la ou collez-la en commentant chaque champ. Dites pourquoi chaque paramètre est là
4. Lire la réponse à voix haute : marquez une pause sur le JSON. Désignez le champ utile pour la suite

Terminez en annonçant la suite : « Cet id, on s’en sert pour le paiement — ce sera la prochaine vidéo. »

Rendre le JSON et le code lisibles

C’est là que la plupart des vidéos d’API échouent. La requête passe, la réponse remplit l’écran, et le spectateur découvre un mur d’accolades illisible.

• Formatez tout : passez par jq ou activez la mise en forme du client
• Repliez l’accessoire : la plupart des clients API savent replier des sections. Repliez les métadonnées dont personne ne se soucie
• Zoomez sur le champ clé : un zoom sur les deux lignes qui comptent vaut mieux que n’importe quel commentaire. Dans Recorded, ajoutez-le ensuite dans l’éditeur, pour rester concentré sur vos appels pendant l’enregistrement
• Ajoutez un texte pour nommer le champ : une étiquette pointant subscription_status se lit plus vite qu’elle ne se prononce
• Coupez l’attente : latence réseau, boucles de polling et recompilations sont du temps mort. Coupez, et indiquez la durée écoulée par un court sous-titre

Commenter comme un collègue, pas comme une spécification

La description formelle figure déjà dans la référence. Votre voix off doit dire ce que la doc ne peut pas dire :

• « Cet en-tête, c’est celui que tout le monde oublie. »
• « Oui, ce champ est obligatoire même s’il a l’air facultatif. »
• « Si vous avez un 422 ici, c’est presque toujours le format de date. »

Ces remarques sont le véritable produit d’une vidéo de documentation. Notez-en trois ou quatre avant d’enregistrer : concentré sur votre frappe, on les oublie vite.

Des clips courts et modulaires

Une visite guidée de l’API de vingt minutes meurt dès qu’un endpoint change. Des clips de deux à quatre minutes centrés sur une seule tâche durent beaucoup plus longtemps et s’intègrent juste à côté de la section de référence qu’ils expliquent.

Modulaire veut aussi dire réenregistrable. Quand la forme du payload change, vous refaites un clip de quatre-vingt-dix secondes au lieu de remonter une longue vidéo.

Anticiper l’évolution de l’API

La vidéo de documentation vieillit plus vite que le texte. Intégrez-le dès le départ :

• Dites et affichez le numéro de version, pour qu’une vidéo périmée le paraisse immédiatement
• Évitez les éléments d’interface datés — une refonte du tableau de bord vieillit une vidéo plus vite qu’un changement d’API
• Conservez les enregistrements sources et les fichiers projet, pas seulement les exports : un remontage ne doit pas devenir un retournage
• Nommez les fichiers par endpoint et version pour repérer après une release ce qu’il faut mettre à jour
• Repassez les clips à chaque version majeure et refaites ceux qui sont devenus faux

Une vidéo courte et honnête du trimestre dernier ne pose aucun problème. Une vidéo qui montre avec assurance un endpoint disparu, elle, coûte votre crédibilité.

Publier là où la question se pose

La vidéo d’API la mieux placée est intégrée directement dans la page de référence de l’endpoint, pas rangée dans une vidéothèque que personne ne visite. Au-delà de deux minutes, ajoutez des chapitres ou des repères temporels, placez sous le lecteur le code complet en texte copiable, et exportez un court GIF de la réponse réussie pour la page de démarrage rapide.

Aide-mémoire

• Compte sandbox avec clés jetables
• Données de test réalistes
• Notifications coupées, historique shell nettoyé
• Polices agrandies, fenêtres disposées
• Structure objectif → auth → requête → réponse
• JSON formaté, zoom sur les champs clés
• Temps d’attente coupés
• Version affichée à l’écran
• Intégrée à côté de la section de référence
• Code copiable publié avec la vidéo

La référence dit aux développeurs ce qui est possible. Un bon enregistrement leur montre que ça fonctionne vraiment — et c’est généralement ce qui les mène à leur premier appel réussi.