Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- OpenMRS.org
- Rédacteur technique:
- batbrain7
- Nom du projet:
- Documentation de l'API REST OpenMRS
- Durée du projet:
- Durée standard (trois mois)
Project description
Je décomposerai ma proposition en différentes sections et suivrai la procédure, comme la documentation sur l'API Google Maps et celle sur l'API GitHub.
En plus de cela, je voudrais également proposer une structure de fichier readme pour la documentation de l'API réalisée par realworld.io : https://github.com/gothinkster/realworld/tree/master/api
Personnellement, j'ai trouvé cette documentation très facile à comprendre et à utiliser.
Ma proposition se composerait principalement de trois sections :
Une section qui donnerait une présentation rapide de l'API, d'OpenMRS, de son utilisation et des prochaines étapes.
Comment obtenir la clé API et l'authentification nécessaires en général pour effectuer la requête API. Il s'agit d'un exemple des types d'authentification présents dans l'API, ainsi que des clés et des valeurs qui doivent être présentes pour elle, ainsi que des types de valeurs acceptés correspondant à la clé dans cette partie. Un exemple de code dans n'importe quelle langue serait utile pour comprendre comment écrire les en-têtes, les formats de réponse et d'autres paramètres de requête dans l'API.
Les types de réponses récupérés par l'API, les types de JSON ou tout autre type de résultat renvoyé par les API doivent être mentionnés.
Les différents chemins d'API et tous les paramètres à envoyer avec ceux-ci, les en-têtes et autres éléments. Chaque API sera accompagnée d'exemples de code dans quelques langues qui décrivent comment la requête est effectuée lors de la rédaction du code. En outre, les codes d'erreur généraux pouvant être rencontrés avec chaque API doivent également être mentionnés.
Il s'agit d'une idée générale de la façon dont la documentation sera définie pour l'API REST.
Le calendrier du projet est le suivant :
1er août au 1er septembre
Me familiariser avec mon mentor et discuter plus en détail du niveau de documentation requis dans différentes parties du codebase, et aussi de la profondeur à laquelle aller dans la documentation de bas niveau par rapport à celle de haut niveau. Je vais également passer ce temps à comprendre le codebase et à étudier les concepts afin de pouvoir les documenter plus efficacement.
Semaines 1 et 2
Je vais mettre à jour et développer le guide des contributeurs. Je vais améliorer la documentation sur la compilation du code source. Je vais également ajouter une section sur la façon dont les nouveaux contributeurs peuvent aider à la documentation. Je vais étudier la documentation des différentes API, commencer par l'introduction et ajouter l'authentification pour l'API.
Semaines 3 à 8
Je vais ajouter les routes et les réponses de l'API, ainsi que des exemples de code pour chaque type d'API (il peut y avoir des types d'API similaires).
Semaines 9 et 10
Ajouter la structuration de la documentation de l'API à l'aide de liens, c'est-à-dire un index lié pour la documentation longue de l'API, et la diviser davantage sur une base différente (sections de code, présentation, paramètres, points de terminaison racine, etc.)
Dernière semaine
Je vais utiliser la dernière semaine pour préparer mon rapport final sur le travail effectué au cours de ma période de documentation de 12 semaines. Je vais également profiter de ce temps pour examiner et finaliser la documentation.