Estándares de documentación / estructura / estilo para servicios web [cerrado]

Question

¿Alguien puede recomendar pautas para la documentación de alto nivel de los servicios web?

Esta es la documentación que debe permitir que alguien sin conocimiento sobre un servicio web en particular obtenga una comprensión básica de su razón de ser, su hoja de ruta y ejemplos de su uso.

Dicha documentación debe caber en dos lados impresos de papel de tamaño A4 / Carta y llevar a alguien menos de 10 minutos para leer.

Tenga en cuenta que esto es complementario a la documentación de API de bajo nivel que un desarrollador usaría para consumir la interfaz.

Answer 1

No estoy seguro de tener directrices, pero puedo mostrarle un ejemplo de algo que encontré como un buen conjunto de documentos para una API de servicios web.

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

Las páginas de la API de Flickr están establecidas en una forma muy legible. Esta página básicamente tiene:

• Enlaces a páginas de resumen
• Escrituras de escenarios comunes (cargando fotos en esta instancia)
• Información sobre herramientas para consumir la API
• Descripciones detalladas de cada API método, agrupado por actividad

En particular, las páginas que describen los puntos de acceso comunes (cargar una foto, reemplazar una foto) son, para mí, vitales. Le muestran a un consumidor de su API cómo hacer las cosas comunes y cómo espera que la gente use su API. El último punto es importante: quiere decir "hey, esperamos que nos llame así, utilizando estos métodos, con este tipo de manejo de errores". Muestre a sus usuarios las mejores prácticas sobre el uso de API y se ahorrará una gran cantidad de llamadas de soporte.