Webサービスのドキュメント標準/構造/スタイル[終了]

Question

Webサービスの高レベルなドキュメントのガイドラインを誰でも推奨できますか？

これは、特定のWebサービスに関する知識のない人が、その存在理由、ロードマップ、およびその使用例についての基本的な理解を得られるようにするためのドキュメントです。

このような文書は、A4 /レター用紙の印刷された両面に収まり、誰かが読むのに10分もかかりません。

これは、開発者がインターフェースを使用するために使用する低レベルAPIドキュメントを補足するものであることに注意してください。

Answer 1

ガイドラインがあるかどうかはわかりませんが、WebサービスAPIの優れたドキュメントセットであることがわかった例を紹介できます。

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

Flickr APIページは非常に読みやすい形式で設定されています。このページには基本的に次のものがあります：

• 概要ページへのリンク
• 一般的なシナリオの説明 （このインスタンスで写真をアップロード）
• APIを使用するツールに関する情報
• 各APIの詳細な説明 アクティビティ別にグループ化されたメソッド

特に、一般的なアクセスパターン（写真のアップロード、写真の置き換え）を説明するページは、私にとって非常に重要です。彼らはあなたのAPIの消費者に一般的なことをする方法とあなたがあなたのAPIを使うことを期待する方法を示します。最後の点は重要です-「ちょっと、この種のエラー処理を使って、これらのメソッドを使用して、このように電話してください」と言いたいです。 APIの使用に関するベストプラクティスをユーザーに示すことで、サポートコールの負荷を軽減できます。