Article original : How to Write Good API Documentation
Imaginez que vous venez d'acheter un nouveau système de home cinéma et que vous allez le configurer. Que faites-vous en premier ?
Heureusement, vous avez un manuel d'utilisation pratique pour vous aider. Vous n'avez qu'à suivre les étapes détaillées dans le manuel, et voilà ! Votre système de home cinéma est prêt à diffuser vos chansons préférées.
Tout comme un manuel d'utilisation vous guide à travers la configuration et l'installation, la documentation d'API peut vous aider à configurer une API.
Qu'est-ce que la documentation d'API ?
Avant de plonger dans la documentation d'API, permettez-moi de vous expliquer brièvement ce qu'est une API et ses fonctions de base.
API est l'acronyme de Application Programming Interface (Interface de Programmation d'Applications).
Connexion des appareils aux bases de données via API
Que vous soyez un codeur débutant ou un développeur avancé, vous rencontrerez souvent ce terme dans votre parcours de développement logiciel. C'est le pont entre votre ordinateur, votre téléphone mobile ou votre application et des ressources externes.
En d'autres termes, les API donnent à votre logiciel la capacité d'interagir avec d'autres programmes logiciels, bases de données ou ressources. Au lieu d'écrire le programme pour une fonctionnalité particulière de votre application, vous pouvez utiliser une API déjà disponible pour une fonctionnalité similaire.
De nombreuses API sont publiques (gratuites) tandis que d'autres sont privées et nécessitent un paiement pour une clé privée qui vous permet d'accéder à l'API. Il existe différents types d'API comme REST (Representational State Transfer), SOAP (Simple Object Access Protocol), et d'autres.
Passons à autre chose – alors, qu'est-ce que la documentation d'API ? Eh bien, c'est un guide écrit indiquant les fonctions de l'API, comment l'intégrer dans votre programme, et les cas d'utilisation de l'API, avec des exemples.
Gardez à l'esprit que la documentation d'API est un contenu technique. Cela signifie qu'elle contiendra certains termes techniques, mais doit rester lisible et facile à comprendre.
Qui devrait rédiger la documentation d'API ?
Les API sont construites par des développeurs de logiciels. Puisque les développeurs de logiciels sont directement impliqués dans la construction et l'utilisation des API, il est plus facile pour eux de créer la documentation.
L'inconvénient des développeurs de logiciels rédigeant la documentation d'API est qu'ils écrivent sous un angle très technique, ce qui peut rendre le document assez difficile à comprendre. Un autre problème est que cela prendra plus de temps au développeur d'API de créer le document tout en développant l'API.
Une bonne alternative est donc d'assigner la tâche de documentation d'API à un rédacteur technique. Un rédacteur technique est quelqu'un qui combine l'expertise de la rédaction de contenu et des connaissances techniques pour produire une documentation qui n'est pas seulement technique, mais aussi informative et compréhensible.
Le rédacteur technique apprend à connaître l'API des développeurs d'API, puis crée des tutoriels, des exemples et d'autres contenus à des fins de documentation.
Pendant ce temps, les développeurs d'API supervisent le rédacteur technique pour s'assurer que la documentation écrite est précise, et ils peuvent fournir plus d'informations au rédacteur lorsque cela est nécessaire.
L'objectif est que tout le monde travaille ensemble pour produire une documentation qui explique pleinement l'API et guide les utilisateurs sans confusion.
Si vous êtes intéressé par la rédaction de documentation pour une API, mais que vous ne savez pas où ou comment commencer, cet article vous aidera à démarrer.
Je peux sentir votre excitation d'ici, alors plongeons-nous dedans !
Comment commencer à rédiger la documentation d'API
Lors de la rédaction de la documentation d'API, commencez par créer plusieurs plans. Cela vous donnera un aperçu de ce que vous avez l'intention d'écrire.
La prochaine chose à faire est de recueillir des informations pour chacun des plans que vous avez créés. Cela peut être réalisé en obtenant la description de l'API, le langage utilisé, d'autres références et des cas d'exemples des développeurs d'API. Vous pouvez également consulter une démonstration en direct de l'API afin d'avoir une expérience directe de son fonctionnement.
Enfin, combinez les détails que vous avez recueillis et organisez-les dans une séquence logique.
N'oubliez pas de relire votre document et de le partager avec les développeurs d'API pour toute correction ou ajout avant de le rendre public.
Maintenant que vous savez par où commencer, comment pouvez-vous assembler les morceaux pour qu'ils forment un tout significatif ?
Que inclure dans la documentation d'API
1. Un aperçu
Cela est similaire à la page de résumé d'un rapport de projet.
L'aperçu doit contenir un résumé de l'API et le problème qu'elle résout. Il pourrait également inclure les avantages de l'utilisation de cette API particulière par rapport à d'autres API similaires.
2. Tutoriels
C'est la partie principale de la documentation.
Elle doit inclure les différents formats de contenu que vous utilisez pour expliquer le concept de l'API à l'utilisateur. Elle peut également inclure des liens de référence et un guide étape par étape pour intégrer l'API et la consommer afin qu'elle fonctionne correctement.
3. Exemples
Une fois que vous avez expliqué comment l'API fonctionne et/ou fourni des étapes détaillées, il est bon de montrer des exemples d'appels, de réponses, de gestion des erreurs et d'autres opérations qui ont à voir avec la manière dont le développeur interagit avec l'API.
4. Glossaire
Bien que cela soit facultatif, je recommande d'ajouter une page de glossaire pour votre documentation d'API.
Pour éviter d'ennuyer l'utilisateur avec de longs blocs de texte, les explications des divers termes, schémas, images, etc., que vous utilisez tout au long de la documentation peuvent tous être poussés vers le glossaire. Ensuite, vous pouvez référencer ces éléments dans la documentation et lier au glossaire.
Comment rédiger une documentation d'API utile
Connaître l'API
Comme nous venons de le discuter, vous devriez avoir une connaissance directe de l'API que vous documentez. Souvenez-vous, votre objectif est de guider les utilisateurs potentiels qui pourraient ne pas avoir de connaissances sur l'API. Vous ne voudriez pas les confondre, n'est-ce pas ?
Si vous avez une solide compréhension de l'architecture du produit, de sa fonctionnalité et d'autres informations vitales, vous serez en mesure de rédiger la partie description du produit de l'API efficacement sans faire de devinettes.
Si vous n'êtes pas bien informé ou pleinement convaincu de l'API sur laquelle vous écrivez, prenez le temps de faire vos recherches et de recueillir autant d'informations que possible. Utilisez l'API vous-même afin de gagner une compréhension importante de son fonctionnement.
Utiliser un contenu relatable
La documentation d'API ne se limite pas aux guides écrits. Vous pouvez utiliser des vidéos courtes ou des diapositives PowerPoint pour illustrer l'intégration de l'API.
Énoncez différents cas d'utilisation lors de la rédaction de la documentation. Cela aidera les lecteurs à reconnaître celui qui est similaire au leur, ou à en trouver un auquel ils peuvent facilement s'identifier.
De plus, incluez quelques extraits de code là où et quand vous pensez qu'ils sont nécessaires. Cela permettra aux lecteurs de suivre tout en parcourant la documentation. Comme le dit le proverbe populaire : "Dis-moi et j'oublierai. Enseigne-moi et je me souviendrai. Implique-moi et j'apprendre."
Soyez clair, même si vous devez être technique
Les API sont des guides pour les logiciels ou le matériel, vous devrez donc utiliser certains termes techniques lors de la rédaction de la documentation. Si vous essayez d'être un rédacteur technique, résistez à la tentation d'être ambigu.
Un bon document n'est pas celui avec des constructions grammaticales complexes, mais plutôt celui qui est relatable, direct et clair. Il ne peut être relatable que s'il est écrit dans un langage simple et compréhensible.
Votre documentation d'API doit être sous la forme la plus simple possible, mais elle ne doit pas omettre de détails importants. De plus, assurez-vous d'expliquer les acronymes et les termes techniques la première fois que vous les utilisez, ou mettez-les dans un glossaire vers la fin de la documentation.
Énumérez le guide
La documentation est plus facile à comprendre si le contenu est énuméré. C'est une raison majeure d'écrire de manière concise.
Numéroter ou énumérer le guide en étapes aide l'utilisateur à comprendre ce qu'il doit faire à tout moment. C'est similaire à lire l'alphabet de A à Z.
Avec des étapes claires, les utilisateurs peuvent facilement revenir en arrière s'ils rencontrent une erreur.
Vérifiez les erreurs
Autant de fois que vous lisez un document, il y aura toujours quelque chose à changer, à mettre à jour, ou même à supprimer. C'est une expérience typique avec les écrivains, et cela ne devrait pas vous contrarier.
L'or passe par plusieurs fourneaux ardents avant de devenir raffiné. Disons simplement que votre documentation devrait passer par un processus similaire (pas un fourneau ardent cependant) pour qu'elle sorte comme un document bien préparé.
Un processus de révision approfondi peut vous aider à minimiser les erreurs et à produire une documentation claire.
Les meilleurs outils pour la documentation d'API
La rédaction de la documentation d'API peut être assez chronophage et difficile à maintenir. Mais un bon outil de documentation peut atténuer la plupart, sinon la totalité, de ces problèmes.
Il existe de nombreux outils pour faciliter votre parcours de documentation d'API. L'avantage d'utiliser des outils est les fonctionnalités collaboratives et les modèles standard que ces outils fournissent, plutôt que de commencer à partir de zéro.
Voici une liste de quelques outils populaires et leurs avantages.
Postman
Postman est une plateforme pour construire et maintenir des API avec des fonctionnalités pour créer de la documentation d'API.
Postman utilise son outil de documentation lisible par machine pour rendre le processus de documentation d'API plus facile et plus rapide. Vous pouvez vous inscrire à Postman gratuitement et l'installer sur votre PC.
Bien que Postman fournisse des mises à jour à toute la documentation d'API qu'il produit automatiquement, son interface utilisateur peut être difficile à comprendre au début.
DapperDox
DapperDox est un outil de documentation d'API open source qui offre divers thèmes pour créer votre document. Cet outil combine des diagrammes, des spécifications et d'autres types de contenu pour vous offrir une meilleure documentation.
Il a l'avantage de permettre aux auteurs d'écrire en markdown flavored GitHub, mais les mises à jour pour cet outil sont irrégulières.
SwaggerHub
SwaggerHub est un outil de documentation d'API populaire pour de nombreux rédacteurs techniques car il est interactif et facile à utiliser.
Bien qu'il soit convivial pour les débutants, il nécessite un paiement pour toute utilisation autre que personnelle. Donc, si vous faites partie d'une organisation et souhaitez utiliser SwaggerHub, votre organisation devra payer pour cela.
Que vous sélectionniez les outils listés ici ou une alternative, vous devriez considérer les points suivants :
- Dans quel cadre utiliserez-vous l'outil ? Est-ce pour un usage personnel ou dans le cadre d'une organisation ?
- À quel point êtes-vous technique ? Êtes-vous débutant ou expert ?
- Comment sont l'interface utilisateur et l'expérience utilisateur ?
Quelques exemples impressionnants de documentation d'API
Voici quelques documents d'API qui vous inspireront à commencer à rédiger de superbes documents d'API. Chacun de ces documents détaille l'utilisation de l'API du produit pour les développeurs en étapes faciles et en termes compréhensibles.
Documentation de l'API GitHub
GitHub offre une documentation vraiment utile – ce qui n'est pas une surprise. Consultez leur documentation d'API ici :
L'API REST est une API populaire utilisée par les développeurs pour accéder aux données du web ou d'une base de données. Cette documentation de Github inclut un aperçu, des guides et même du code sur la façon d'utiliser l'API REST dans votre programme.
La partie intéressante de ces documents est que vous pouvez facilement les comprendre, quel que soit votre niveau de compétence.
Documentation de l'API Paystack
Construisez-vous une application qui nécessite des paiements ? Paystack est une solution fintech pour les paiements. Leur équipe fournit des informations détaillées aux développeurs sur la façon d'utiliser l'API Paystack dans vos programmes. C'est comme fournir un manuel sur l'utilisation de l'API pour éviter la confusion lors de l'intégration de l'API dans votre programme.
Documentation de l'API Twitter
La documentation de l'API Twitter explique comment les développeurs peuvent interagir avec l'application. Les documents détaillent clairement les différentes sections (utilisateur, tweets, messages directs, etc.) et leurs opérations.
Bien qu'un accès avec permission soit nécessaire pour plus d'informations, vous pouvez accéder aux bases avec un simple clic sur le lien.
Conclusion
La documentation explique comment un outil fonctionne afin que d'autres puissent l'utiliser correctement. Les documents d'API ne sont pas toujours faciles à créer, mais ce n'est pas aussi difficile de créer une documentation utile que vous pourriez le penser.
Rappelez-vous simplement : commencez par écrire votre premier brouillon, améliorez-le quotidiennement et demandez de l'aide à des mentors ou à des collègues seniors lorsque vous êtes bloqué.
Maintenant, allez-y et rédigez cette documentation d'API qui accompagnera le prochain produit de classe mondiale.