padrões de documentação / estrutura / estilo para serviços Web [fechado]

Question

Alguém pode recomendar orientações para a documentação de alto nível de serviços da Web?

Esta é a documentação que deve permitir que alguém com nenhum conhecimento sobre um serviço Web específico para sair com uma compreensão básica de sua razão de ser, seu roteiro e exemplos de seu uso.

Essa documentação deve caber em dois lados impressos de papel A4 / Carta e levar alguém a menos de 10 minutos para ler.

Note que este é suplementar a documentação da API de baixo nível que um desenvolvedor usaria para consumir a interface.

Answer 1

Eu não tenho certeza que eu tenho diretrizes, mas posso mostrar-lhe um exemplo de algo que eu encontrei para ser um bom conjunto de documentação para a API de serviços web.

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

páginas da API O Flickr constam de uma forma muito legível. Esta página tem basicamente:

• Os links para páginas de informações gerais
• writeups de cenários comuns (Fotos upload neste exemplo)
• Informações sobre ferramentas para consumir a API
• As descrições detalhadas de cada API método, agrupadas por actividade

Em particular, as páginas que descrevem os paterns de acesso comuns (upload de uma foto, substituindo uma fotos) são, para mim, vital. Eles mostram um consumidor de sua API como fazer as coisas comuns e como você espera que as pessoas a usar sua API. Esse último ponto é importante - você quer dizer "hey, esperamos que você chamar-nos como esta, usando estes métodos, com este tipo de tratamento de erros". Mostre a seus usuários algumas das melhores práticas em torno de uso da API e você vai salvar a si mesmo toda uma carga de chamadas de suporte.