Documentation d’API et de SDK

Le marché mondial des API est en pleine croissance

C’est un fait : le marché mondial des API est en pleine croissance.

Par exemple, [Persistence Market Research] (https://www.persistencemarketresearch.com/market-research/cloud-api-market.asp) écrit ceci :

“L’API (Application Programming Interface) est en train de devenir l’un des outils les plus importants pour l’accès aux données. Les entreprises se tournent de plus en plus vers l’utilisation des API pour la transformation numérique. L’API pour les entreprises est en train de devenir le composant clé pour la fusion des anciennes et des nouvelles plates-formes informatiques et pour la capture et le stockage d’une grande quantité de données.(…) Le rapport fourni par Persistence Market Research prévoit une croissance du marché mondial des API de Cloud de manière significative dans la période 2017-2026.”

Cette croissance est également confirmée par ProgrammableWeb: “L’intérêt de fournir des API demeure élevé”.

Croissance des WebAPIs

Crédit image @ProgrammableWeb

La documentation d’API est cruciale

Si le marché des API est en pleine croissance, la demande en documentation d’API pertinente va l’être aussi. Il n’y a pas que vos prouesses techniques qui feront la différence avec vos compétiteurs, il y a aussi votre capacité à se mettre à leur portée en leur expliquant comment intégrer votre API facilement et rapidement. Le temps d’un développeur, c’est de l’argent. Pour éviter d’en perdre et lui faciliter la tâche, il faut donc lui fournir des informations pertinentes et détaillées, ainsi que des exemples de code « prêts à l’emploi ». C’est là le travail du Rédacteur Technique, dont soit dit en passant, le coût est moins élevé que celui d’un développeur.

Un des éléments clés de la rédaction technique dans le domaine des API est la capacité du rédacteur à lire du code dans un ou plusieurs langages, et d’en ressortir les informations utiles.

L’offre de service Coffee Cup en documentation d’API & SDK

Coffee Cup propose des services en documentation d’API et de SDK.

langues La documentation peut être rédigée en français, en anglais ou en allemand.

Ma capacité à lire du code pour en extraire les informations à documenter, ou à savoir où ajouter des descriptions, comprend : JSON, XML, PHP, NODEJS, Javascript, PYTHON and C++. A une époque, j’ai même documenté une API en C.

JAVADOC, Doxygen et les autres documentations d’API

Les API et les SDKs doivent être documentés selon leurs spécifications.

Par exemple, la JAVADOC sera travaillée directement dans le code source JAVA. Doxygen permet de générer de la documentation à partir de sources C++ ainsi que de nombreux autres langages. Plus les commentaires sont riches et pertinents, et meilleure sera la documentation. La documentation étant générée au format HTML, l’utilisation d’un template pour obtenir un rendu séduisant est possible.

La documentation de référence inclut :

  • Description des méthodes, paramètres,
  • Valeurs optionnelles ou requises, préconisations
  • Codes retournés

La documentation utilisateur inclut :

  • Vue d’ensemble, schémas, information de contexte
  • Guide de démarrage
  • Tutoriels
  • Liste des codes erreurs
  • Résolution de problèmes
  • Fonctionnalités par type d’action
  • Glossaire

Si vous préférez que la documentation constitue un ensemble séparé de l’API, c’est également possible. L’information sera “extraite” du code et structurée dans un fichier.

Ecrire la documentation peut nécessiter une collaboration étroite avec l’équipe de développement (ce qui ne veut pas dire permanente).

🔗 Consultez mon Portfolio.

Outils

Doxygen, Visual Studio Code, Git et tout autre outil nécessaire pour lire/modifier du code, Postman, éditeurs de texte, Hugo, Jekyll, Redoc et WordPress.

Le présent site web utilise la syntaxe Markdown, le générateur de site statique Hugo et un sympathique template.