Temps de lecture : 9 minutes
Les API font tourner le monde. Les développeurs utilisent des API presque tous les jours – selon certaines estimations, ils passent plus de 10 heures par semaine à travailler avec des API. Il ne s’agit pas seulement de les utiliser, mais aussi de faire des recherches, de chercher de l’aide sur Google, d’étudier les critiques et, bien sûr, de fouiller dans la documentation. La clarté, la facilité, l’utilité et le support de votre API déterminent l’ensemble de l’expérience du développeur (DX) – une réponse émotionnelle que les développeurs ont au produit. Dans l’économie des API, une excellente expérience du développeur est fondamentale. Les API qui aident les développeurs à réussir et sont agréables à utiliser attireront des tonnes d’utilisateurs et se démarqueront de la concurrence. Et cela commence à l’instant précis où ils ouvrent la documentation pour la première fois.
Voyez cette vidéo pour une introduction à la technologie API
Aujourd’hui, nous allons parler de la façon de favoriser une expérience positive pour les développeurs dans la documentation API. Mais d’abord, nous devons comprendre ce qui fait de mauvaises docs d’API.
Ce que les développeurs détestent dans la documentation des API
La communauté des développeurs est une communauté passionnée. Elle est spécifiquement passionnée par les choses qu’elle n’aime pas. S’ils n’aiment pas une API, c’est la plupart du temps à cause d’une documentation de pacotille, même si le produit est en fait génial. Voici quelques problèmes courants que les développeurs rencontrent avec les docs d’API.
Il n’est pas écrit en utilisant un langage humain simple. C’est un problème courant pour les docs générés automatiquement ou les docs négligés par les créateurs. Bien que de nombreux outils de génération de documentation fassent un excellent travail pour commenter le code, ils ne peuvent pas remplacer les explications réelles en anglais écrites par un développeur ou un rédacteur technique.
Il a très peu d’échantillons de code. C’est une autre extrémité du spectre où les explications sont abondantes, mais où les exemples de code réel sont minimes.
Il n’est disponible que pour les utilisateurs enregistrés. Cette manœuvre pas très habile ne fait rien pour votre marketing. Elle ne fait que frustrer les personnes qui veulent savoir ce que fait votre API avant de décider si elles en veulent (comme toute personne saine d’esprit le ferait).
C’est trop long/Introuvable/inaccessible/n’a pas été mis à jour depuis des années, etc. Créer de bonnes docs est presque aussi important que de construire une bonne API. En effet, les documents mal rédigés ou ceux qui ne peuvent pas être trouvés en tapant simplement sur Google « Product API » font échouer tout l’effort de développement. Si cela vous intéresse, nous avons déjà décrit les spécificités de la documentation technique en général. Mais les documents relatifs aux API méritent un article dédié. Alors, comment rédiger d’excellentes docs d’API ?
Adopter le développement piloté par les spécifications
Le développement piloté par les spécifications (SDD) est similaire au développement piloté par les tests dans lequel vous écrivez des cas de test pour chaque fonctionnalité, puis écrivez le code qui doit les réussir. Dans le SDD, vous créez des docs ou au moins certaines parties en parallèle de la construction d’une API, en suivant souvent un certain format de description d’API appelé spécification.
Une spécification d’API est comme un modèle de vos futures docs, le langage unifié qui décrit la conception de votre API, explique comment elle fonctionne et ce qu’il faut en attendre. Il existe quelques spécifications, comme RAML (RESTful API Modeling Language), OpenAPI (anciennement Swagger) et API Blueprint, mais une tendance se dessine pour combiner toutes les spécifications sous le capot d’OpenAPI.
Ces spécifications ont des outils de documentation préconstruits qui permettent d’écrire et de gérer vos docs. Par exemple, API Console génère automatiquement des docs à partir des formats RAML et OpenAPI et vous aide à les exécuter sur votre application web existante ou en tant qu’app autonome.
API Console vous permet de construire un portail web pour vos docs API à partir des spécifications RAML et OpenAPI
Source : Pawel Psztyc
Alternative aux solutions traditionnelles de docs d’API comme les CMS WordPress ou Drupal, les produits de spécifications d’API sont open source, créés par la communauté de dev pour la communauté de dev, ont des parseurs dans différents langages de programmation et un support constant des créateurs.
Écrire pour le niveau d’entrée
Il y a une raison pour laquelle la documentation technique n’est généralement pas écrite par les développeurs eux-mêmes – c’est le travail des rédacteurs techniques, des experts dans la traduction des aspects techniques dans un format lisible. Mais même les rédacteurs techniques ont tendance à laisser échapper un peu de jargon dans le texte.
Une API comme tout produit logiciel est créée pour un public spécifique. Mais le public de la documentation est vaste. Il existe trois groupes principaux d’utilisateurs de la documentation :
- les développeurs qui interagiront intimement avec les docs
- les décideurs comme les CTO et les architectes de solutions qui veulent déterminer si votre API sera un bon ajustement rapidement
- les observateurs comme les journalistes, les rédacteurs techniques, et même les concurrents qui n’utiliseront jamais nécessairement votre API.
Et même au sein de chacun de ces groupes, il existe des personnes aux compétences, rôles et besoins différents, et toutes doivent avoir une expérience positive avec les docs. Comment les cibler tous ? En ciblant les utilisateurs les moins expérimentés. Alors, comment rédiger des docs pour un nouveau venu ?
Commencez par les opportunités plutôt que par les aspects techniques. Accueillez les utilisateurs avec une histoire convaincante racontant comment votre API peut enrichir leur produit ou décupler la vie des développeurs.
Les docs de l’API Alexa d’Amazon commencent par expliquer ce que fait Alexa et quel avantage elle peut apporter au client
Montrer par où commencer. Les docs d’API sont connus pour être trop écrasants et supposer que les utilisateurs ont une vaste expérience des API. La section de mise en route est obligatoire, et elle doit être écrite avec patience pour un utilisateur potentiel.
Facebook fournit une référence claire pour les débutants et suit le processus de mise en route étape par étape
Créer des instructions pour les cas d’utilisation les plus courants. Vous savez probablement déjà pour quelles fonctions les gens utilisent votre API. Créez des sections distinctes qui les abordent et incluez-y des exemples de messages.
Utilisez un ton conversationnel. La communauté des développeurs est décontractée et informelle, elle n’appréciera donc pas un langage d’entreprise sec, même s’il semble plus » professionnel. » Les bonnes docs parlent toujours aux humains.
Eduquez sur les outils externes. Si votre API nécessite l’utilisation et la compréhension de produits et de concepts tiers comme OAuth ou npm, incluez des liens vers des docs ou des guides d’installation.
Faites en sorte que l’apprentissage soit facile. Les docs d’API ne sont pas des instructions de montage IKEA,;ils sont la source d’apprentissage. Enrichissez votre documentation avec des FAQ, des tutoriels, des blogs et même des vidéos lorsque cela est possible.
Incorporer des sections incontournables
En 2019, SmartBear, le développeur de Swagger, a mené une enquête auprès des développeurs et des utilisateurs d’API. Ils ont trouvé quelles fonctionnalités de la docs sont considérées comme les plus importantes dans la communauté, nous donnant une liste des sections de documentation incontournables que les devs veulent couvrir. Nous allons passer en revue certaines d’entre elles.
SmartBear a sondé 3 000 praticiens des API
Exemples. Les exemples sont généralement présentés comme des morceaux de code, qui sont assez utiles mais peuvent être rendus encore plus pratiques. Par exemple, inclure une transcription des champs comme cela est fait dans les docs Medium ou même créer une API fantaisie pour que les développeurs puissent la tester et l’utiliser en faisant de vrais appels. Les API fantaisie peuvent être facilement partagées via une URL ou sur GitHub, et si elles sont faites à un certain niveau de détail, même utilisées dans le produit final.
Statut et erreurs. Il existe des codes d’état standard et ceux spécifiques à vos API. C’est une bonne idée d’inclure toutes les erreurs qui peuvent être déclenchées par votre API. Les erreurs sont souvent mises sur une page dédiée des docs, mais il est logique de dupliquer certaines d’entre elles directement sous le point de terminaison où elles font le plus surface.
Authentification. La plupart des docs d’API commencent par l’authentification et l’autorisation. Cela devrait couvrir des infos sur la façon d’obtenir une clé d’API et sur la façon d’authentifier les demandes, y compris les erreurs possibles, les délais d’expiration des jetons, et une explication sur la sensibilité de l’authentification (rappelant essentiellement que les clés ne peuvent pas être partagées, et où elles peuvent être utilisées).
Les demandes HTTP. Fournir des requêtes web en HTTP est le strict minimum pour la documentation. On suppose généralement que les devs sauront comment envoyer des requêtes HTTP dans la langue de leur choix, mais parfois, les créateurs d’API incluent des requêtes dans différentes langues. Cela peut être fait automatiquement via des outils de spécification d’API et des outils de gestion d’API comme Postman.
Utiliser une mise en page standard de l’industrie
Si vous utilisez un générateur de documentation, la mise en page est déjà décidée pour vous. La plupart des docs d’API se présentent de la même manière. Si vous en avez utilisé quelques-unes, vous savez comment aborder les nouvelles docs. Pourtant, organiser de grands volumes de données, les rendre trouvables et faciles à naviguer est une tâche complexe. Voici quelques caractéristiques de la mise en page la plus fonctionnelle.
Mise en page dynamique. Vous pouvez reconnaître une API obsolète à sa documentation statique. Une page unique ou même un document PDF ne suffisent pas en 2020. Les docs dynamiques sont faciles à consulter, à mettre à jour et à mettre en signet.
Contenu collant. Non, la barre de navigation ne distrait pas et ne vole pas l’espace précieux de l’écran. Gardez toujours le contenu en vue.
Mise en page sur trois colonnes. Peu utilisée, cette disposition permet d’avoir une autre colonne à droite pour les exemples de code. Bien sûr, cela n’a de sens que si vous avez une tonne de texte et que vous voulez mettre en évidence le code afin que les utilisateurs n’aient pas à faire défiler le texte ou à passer d’un onglet à l’autre.
Les docs de l’API HubSpot utilisent une disposition en trois colonnes
Utiliser des couleurs contrastées pour la syntaxe. Les développeurs passent beaucoup de temps à regarder vos exemples de code, alors rendez-les lisibles et séparez les différents composants par des couleurs.
Cet exemple tiré de la doc sur l’API graphique de Facebook montre également comment vous pouvez utiliser différents onglets pour choisir entre les SDK
État de défilement sauvegardé. C’est un petit détail que tout développeur appréciera. Vous pouvez également utiliser des liens d’ancrage pour spécifier différentes sections de la page au cas où ils copieraient l’URL.
Encouragez les commentaires. Vos docs sont votre principal outil marketing – si les gens les aiment, ils utiliseront votre API plutôt que celle de la concurrence et animeront la communauté autour d’elle. Le message habituel « Cette page vous a-t-elle été utile ? » vous permettra de savoir dans quelle mesure vous répondez aux questions des devs et le formulaire de retour d’information sera utilisé souvent tant que vous le délivrerez.
N’abandonnez pas vos docs
Les docs obsolètes sont la plus grande bête noire des utilisateurs d’API. C’est aussi l’une des erreurs les plus courantes. Les développeurs écrivent souvent sur les mises à jour plusieurs jours après les avoir déployées, se limitant parfois à quelques phrases. Cela se produit parce qu’il n’y a pas de processus établi pour les mises à jour de la documentation et que personne n’en est responsable. Voici comment assurer des mises à jour de docs régulières et utiles.
Préparez les docs avant les mises à jour. Faites-en une étape supplémentaire dans votre plan de lancement, ne les déployez pas avant d’avoir des paragraphes bien écrits, détaillés et édités pour introduire vos mises à jour.
Supprimez régulièrement les données dépréciées. Les docs doivent être revues souvent, au moins une fois tous les quelques mois. Les fonctionnalités de feedback des utilisateurs vous permettront d’attraper les incohérences plus tôt et il devrait toujours y avoir un membre de l’équipe responsable de leur révision et de la réaction aux mises à jour.
Utiliser l’analytique pour améliorer les docs. L’analyse standard des API vous indiquera quels sont les points de terminaison les plus utilisés, vous pouvez donc vous concentrer sur certaines parties de la documentation et fournir des informations plus utiles ou créer des tutoriels dédiés. Surveillez les cas d’utilisation de vos API, car cela vous permettra d’élargir la proposition de valeur et de mettre à jour les docs avec plus de possibilités.
Grands exemples de documentation d’API
Il existe des tonnes de bonnes docs à explorer et à apprendre. En plus des exemples que nous avons partagés tout au long de l’article, en voici d’autres que vous pourrez apprécier et dont vous prendrez note.
Documentation de l’API Medium
Les docs de l’API Medium ne respectent pas nécessairement toutes les règles que nous avons énumérées aujourd’hui, mais elles sont excellentes pour la fonctionnalité limitée que cette API prend en charge – l’affichage et la recherche de publications sur Medium. Elles sont partagées sur GitHub, ont un contenu vraiment court mais clair avec des tonnes d’exemples, chacun se terminant par une transcription de tous les paramètres mentionnés dans le code, y compris les erreurs éventuelles. C’est remarquablement simple, mais fiable – toutes les suggestions peuvent être faites directement sur GitHub et les docs sont régulièrement mises à jour.
Documentation API de Mailchimp
Mailchimp se rend compte que la plupart de son public sont des professionnels du marketing et utilise un langage qui permet même aux non-techniciens de comprendre comment travailler avec ses API. D’un coup d’œil, chaque section suit la même structure :
- ce que fait un endpoint et ce que le guide permettra aux utilisateurs de faire
- ce dont vous aurez besoin – tout accès ou compte qu’un utilisateur doit obtenir en premier
- ce qu’est chaque fonction avec une description textuelle, un exemple de code en plusieurs langues, et parfois des captures d’écran de l’interface.
Il y a même un bouton de copie pour chaque morceau de code – un détail que les non-techniciens apprécieront certainement.
Documentation API de Twilio
Twilio a des docs API fameusement bonnes. Bien que les docs ne soient que la partie émergée de l’iceberg de toute l’aide que Twilio partage – il existe des SDK dans plusieurs langues et des exemples d’applications pour iOS, Android et le web. Tout d’abord, elles suivent la logique à trois colonnes avec le code directement à droite du guide. Les actions les plus simples sont expliquées en détail, avec des tonnes de liens pour des informations supplémentaires et des captures d’écran. Les commentaires sont également encouragés via un bouton « Rate this page » et des liens vers l’équipe de support et le tag sur StackOverflow.
Documentation API Spotify
Bien que les docs API web de Spotify soient très typiques, ils ont beaucoup d’informations supplémentaires dans sa plateforme Spotify for Developers. Il existe des démos pour les fonctions de base, des applications fictives, des exemples concrets construits à l’aide des API et des widgets Spotify, des wrappers pour différents langages de programmation et, bien sûr, la console. La console est en fait une documentation interactive dans laquelle vous pouvez saisir vos données (ou celles d’un échantillon) et explorer les points de terminaison en direct. Des produits puissants accompagnés d’une solide base de connaissances font de Spotify un partenaire fiable avec lequel les développeurs aiment travailler.
Traiter les docs avec soin
La documentation est le seul point de contact que vous aurez avec la plupart de votre public, vous devez donc apprendre à communiquer clairement à travers elle. Le meilleur conseil ici est d’en faire le travail de quelqu’un. Il s’agit souvent d’un rédacteur technique qui sait comment s’adresser à des publics de compétences différentes, qui peut traduire les propos des développeurs en points exploitables, qui surveille la maintenance et la mise à jour de la documentation en temps voulu. Mais il est possible de gérer une documentation de qualité même sans l’aide d’un expert. Les outils de gestion d’API comme Swagger UI, Spotlight, Apiary et les outils de spécification de docs disposent d’une large fonctionnalité pour vous aider à faire des docs que les développeurs vont adorer.