Normes / structure / style de la documentation pour les services Web [fermé]

Question

Quelqu'un peut-il recommander des instructions pour la documentation de haut niveau des services Web?

Il s’agit de la documentation qui devrait permettre à une personne non renseignée sur un service Web donné de se familiariser avec les bases de sa raison d’être, de sa feuille de route et des exemples de son utilisation.

Cette documentation doit tenir sur deux faces imprimées de papier A4 / Letter et prendre moins de 10 minutes à lire.

Notez qu'il s'agit d'un complément à la documentation de l'API de bas niveau qu'un développeur utiliserait pour utiliser l'interface.

Answer 1

Je ne suis pas sûr d'avoir des directives, mais je peux vous montrer un exemple de ce que j'ai trouvé être un bon ensemble de documents pour une API de services Web.

http://www.flickr.com/services/api/

Les pages de l'API Flickr sont présentées sous une forme très lisible. Cette page contient essentiellement:

• Liens vers les pages d'aperçu
• Écrits de scénarios courants (téléchargement de photos dans cet exemple)
• Informations sur les outils permettant de consommer l'API
• Descriptions détaillées de chaque API méthode, regroupée par activité

En particulier, les pages décrivant les modèles d'accès courants (téléchargement d'une photo, remplacement d'une photo) sont, pour moi, essentielles. Ils montrent au consommateur de votre API comment faire les choses courantes et comment vous attendez des gens qu'ils utilisent votre API. Ce dernier point est important - vous voulez dire "Hé, nous nous attendons à ce que vous nous appeliez ainsi, en utilisant ces méthodes, avec ce type de traitement des erreurs". Présentez à vos utilisateurs les meilleures pratiques d'utilisation de l'API et vous éviterez de nombreux appels d'assistance.