Стандарты документации / структура / стиль для веб-сервисов [закрыт]

Question

Кто-нибудь может порекомендовать рекомендации по высокоуровневой документации веб-сервисов?

Это документация, которая должна позволить кому-либо, не имеющему знаний о конкретном веб-сервисе, получить базовое представление о причине его существования, его дорожной карте и примерах использования.

Такая документация должна умещаться на двух печатных сторонах листа формата А4/Letter, и чтение ее должно занимать не более 10 минут.

Обратите внимание, что это дополнение к низкоуровневой документации API, которую разработчик будет использовать для использования интерфейса.

Answer 1

Я не уверен, что у меня есть рекомендации, но я могу показать вам пример того, что, по моему мнению, является хорошим набором документов для API веб-служб.

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

Страницы API Flickr представлены в очень удобочитаемой форме.На этой странице в основном есть:

• Ссылки на обзорные страницы
• Описание распространенных сценариев (в данном случае загрузка фотографий)
• Информация об инструментах для использования API
• Подробные описания каждого API метод, сгруппированный по видам деятельности

В частности, страницы, описывающие общие методы доступа (загрузка фотографии, замена фотографий), для меня жизненно важны.Они показывают потребителю вашего API, как выполнять обычные действия и как вы ожидаете, что люди будут использовать ваш API.Этот последний момент важен - вы хотите сказать: "Эй, мы ожидаем, что вы позвоните нам вот так, используя эти методы, с такой обработкой ошибок".Покажите своим пользователям несколько рекомендаций по использованию API, и вы избавите себя от множества обращений в службу поддержки.