Dokumentationsstandards / Struktur / Stil für Web-Services [geschlossen]

Question

Kann jemand empfehlen Richtlinien für High-Level-Dokumentation von Web-Service?

Dies ist die Dokumentation, dass jemand ohne Wissen über einen speziellen Web-Service zu kommen weg mit einem grundlegenden Verständnis des Grundes für sein, ihr Fahrplan und Beispiele für deren Nutzung ermöglichen soll.

Eine solche Dokumentation sollte auf zwei gedruckte Seiten A4 / Letter Papier passen und jemand weniger als 10 Minuten in Anspruch nehmen zu lesen.

Beachten Sie, dass dies auf die Low-Level-API-Dokumentation Zusatz ist, dass ein Entwickler die Schnittstelle verbrauchen würde verwenden.

Answer 1

Ich bin nicht sicher, ich habe Richtlinien, aber ich kann Ihnen ein Beispiel für etwas zeigen, dass ich für einen Web-Services-API ein guter Satz von docs erwiesen.

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

Die Flickr-API-Seiten sind in einer sehr lesbaren Form dargestellt. Diese Seite im Grunde hat:

• Links zur Übersicht Seiten
• Zuschreibungen von gemeinsamen Szenarien (Fotos in diesem Fall das Hochladen)
• Info über Werkzeuge, um die API
verbrauchen
• Detaillierte Beschreibungen der einzelnen API Verfahren, gruppiert nach Aktivität

Insbesondere die Seiten, die die gemeinsamen Zugriff paterns (Hochladen eines Fotos, das Ersetzen eines Fotos) sind für mich lebenswichtig beschreiben. Sie zeigen einen Verbraucher Ihrer API wie die gemeinsamen Dinge zu tun und wie man die Leute erwarten, dass Ihre API verwenden. Dieser letzte Punkt ist wichtig - Sie sagen wollen: „Hey, wir erwarten, dass Sie uns so nennen, diese Methoden verwenden, mit dieser Art von Fehlerbehandlung“. Zeigen Sie Ihren Besuchern einige Best-Practice um API-Nutzung und Sie finden sich eine ganze Menge von Support-Anrufe speichern.