Standard / struttura / stile della documentazione per i servizi Web [chiuso]

Question

Qualcuno può raccomandare linee guida per la documentazione di alto livello dei servizi Web?

Questa è la documentazione che dovrebbe consentire a qualcuno che non ha conoscenza di un particolare servizio Web di venire a conoscenza di una base della sua ragione di essere, della sua tabella di marcia e degli esempi del suo utilizzo.

Tale documentazione dovrebbe adattarsi a due lati stampati di carta A4 / Letter e richiedere una lettura a meno di 10 minuti.

Nota che questo è supplementare alla documentazione API di basso livello che uno sviluppatore userebbe per utilizzare l'interfaccia.

Answer 1

Non sono sicuro di avere delle linee guida, ma posso mostrarti un esempio di qualcosa che ho trovato essere un buon insieme di documenti per un'API dei servizi Web.

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

Le pagine dell'API di Flickr sono strutturate in un formato molto leggibile. Questa pagina ha sostanzialmente:

• Collegamenti alle pagine di panoramica
• Scritture di scenari comuni (caricamento di foto in questo caso)
• Informazioni sugli strumenti per utilizzare l'API
• Descrizioni dettagliate di ciascuna API metodo, raggruppato per attività

In particolare, le pagine che descrivono i paterns di accesso comuni (caricamento di una foto, sostituzione di una foto) sono, per me, fondamentali. Mostrano a un consumatore della tua API come fare le cose comuni e come ti aspetti che le persone usino la tua API. Quest'ultimo punto è importante: vuoi dire "ehi, ci aspettiamo che tu ci chiami così, usando questi metodi, con questo tipo di gestione degli errori". Mostra ai tuoi utenti alcune best practice sull'utilizzo delle API e ti risparmierai un sacco di chiamate di supporto.