"Hello World!"
コーダーのための API ドキュメント執筆ガイド
Peter Gruenbaum
これまでに、開発した API のドキュメントを執筆するよう上司から求められたことがありますか。実際のところ、ほとんどの開発者は、コードの作成は好きでも、執筆は嫌いです。また、執筆作業のために、機能開発やバグの修正など、やらなければならない重要な作業の時間が奪われます。
読者にとってストレスになり、困惑の種になる API ドキュメントが多いのも驚くことではありません。API ドキュメントには、しかるべき注意が払われることがほとんどないのですから。
この記事は、API ドキュメントを執筆する方法についてのガイドです。ここでは、API ドキュメントの最も重要な構成要素について説明し、効果的な API ドキュメントにする方法についていくつか提案します。また、最大限の効果を得るにはどの部分に時間と注意を注ぐべきかということも含め、優れた概要、サンプル コード、およびリファレンスを作成するためのヒントも提供します。
API のドキュメントを執筆する理由
では、技術面以外の問題から見て行きましょう。初めてプログラミング言語が開発されて以来、API ドキュメントが提供され続けています。質の高いドキュメントを作成するための効果的なプロセスが開発されるだけの十分な時間があったにもかかわらず、いまだにしっかりと記述された API ドキュメントにお目にかかることはめったにありません。優れた API ドキュメントが執筆されないのはなぜでしょう。
第一に、ドキュメントが優先されることはまずありません。ドキュメントはソフトウェア プラットフォームの採用率に大きく影響しますが、ドキュメントの実際の効果を測ることは困難です。そのため、ドキュメントの執筆に十分な時間と予算が割り当てられることはほとんどありません。開発者がドキュメントの作成を依頼されるとき、通常は他の職務に加えて作業することになり、既に過密なスケジュールをやりくりして、執筆作業を予定に組み込まなければなりません。
第二に、コードの開発スキルとドキュメントの執筆スキルは、2 種類の異なるスキルです。開発者は、各自の母国語ではない言語でのドキュメントの執筆を依頼されることもあります。開発者が英語圏で生まれ、英語でのドキュメントの執筆を依頼されたとしても、学校では文学や社会科の授業でが苦手で、その時間を数学や科学の授業での問題解決に充ててしまった可能性も少なくはありません。
優れた API ドキュメントを執筆する第一歩は、上司にそのための時間と予算の確保をお願いすることです。上司に伝えるべきポイントは次の 2 つです。
- 優れたドキュメントは、開発者にとってフラストレーションが少なくなるため、プラットフォームの採用率を高めることができる。
- 優れたドキュメントは、開発者の疑問に対する答えを見つけやすいため、サポート費用が削減される。
ドキュメントの執筆を楽しめない場合や、仕事が多すぎてまったく余裕がない場合は、優れたドキュメントの重要性を論じることが難しいかもしれません。そのときは、別の手段があります。予算が十分にあれば、開発者から情報を収集してドキュメントを執筆するテクニカル ライターを雇うことができます。
開発者と同様、テクニカル ライターの持つ経験と専門分野はさまざまです。多くのテクニカル ライターは、エンド ユーザー向けのドキュメントとサポートの経験の方が豊富です。しかし、API ドキュメントの場合は、ソフトウェア開発者としての経歴のあるライターを探すことをお勧めします。多くの企業では、このようなライターにはプログラマー/ライターなどの肩書きが付けられています。
コーディングの経験を積んだテクニカル ライターは、ソフトウェア プラットフォームを運用できるようにするまでに開発者が経験する苦しみと、優れたドキュメントがプラットフォームの開発改善にいかに役立つかを理解できます。また、コードを読み、ライブラリを理解できるだけの言語、アルゴリズム、およびパターンの専門知識も備えている必要があります。このような知識と経験があれば、ライターと開発チームとの間の技術的話し合いは、より端的で実りあるものになります。
とは言え、テクニカル ライターを雇う予算がない場合は、開発者自身がドキュメントを執筆する必要があります。新機能を開発する場合と同様、必ず、ドキュメント執筆の時間を確保しなければならないことを上司に理解してもらうようにしてください。
API ドキュメントの構成要素
優れた API ドキュメントは、次の 4 つの要素から成り立っています。
- 概要: プラットフォームを使用するメリットを説明し、場合によっては、プラットフォームのアーキテクチャを説明します。
- 基本操作の説明: 詳細手順を紹介するチュートリアルや簡単なウォークスルーの形で、基本操作を可能にします。
- サンプル コード: コーディングの土台として使用できる、詳細なコメントを添えたコード サンプルを提供します。
- リファレンス: 各クラス、メンバー、関数、XML 要素の詳細を提供します。
開発者が API についての資料を読み始めるときに、最初に知る必要がある情報は、その API の対象ユーザーと使用目的です。開発者がこのことを理解できないと、すぐに見限られて、別のものが採用されてしまいます。残念なことに、この情報はしばしば忘れられがちです。API を開発する側にとっては、こうした情報はわかりきったことですが、利用する側にとってはそうではありません。
API を使用する状況について、わかりやすい例をいくつか用意します。既存のユーザーがいる場合や、さらには見込みユーザーがいる場合は、それらのユーザーを実例として使用します。ソフトウェア プラットフォームのメリットを列挙し、理想的には既存の方法と対比します。この種の情報は、多くの場合、プロジェクト マネージャーが所持しています。
概要は、API の全体的アーキテクチャを説明する格好の場でもあります。ある種の API (多くの Web API など) では、アーキテクチャの説明が必要ないほど API がシンプルな場合もあります。しかし、多数のクラスがあり、継承構造を持つ複雑な API のドキュメントを執筆する場合は、図を添えたアーキテクチャの完全な説明が、API を理解するうえで多くの場合役立ちます。
基本操作の説明
開発者がその API を試してみようと決めたら、最初に必要となる情報は基本操作の方法です。2009 年に私の会社 (SDK Bridge LLC) では、ドキュメントについてのアンケート調査を実施しました。このときの回答で一貫して指摘された最大のポイントの 1 つが、基本操作についての支援が求められていることでした (私の記事「SDK ドキュメントに関する調査」(tinyurl.com/35l66yk) を参照してください)。これは、採用に大きく影響します。開発者は基本操作が理解しにくいことがわかると、すぐにあきらめて、目的を達成できる別の方法を探すでしょう。
開発者に基本操作方法を伝える優れた方法は、チュートリアルを利用することです。この方法は、多くの場合、説明の文章やアーキテクチャの図よりも大きな効果があります。チュートリアルでは、API のしくみを実際に確認できる簡単なアプリケーションを作成するプロセスを順を追って紹介します。この場合、最初は、開発環境のセットアップや認証のための資格情報の取得など、プログラミング以外の作業が多くなります。その後、徐々にコードを追加して、API から簡単な作業を実際に実行できるようにします。可能であれば、開発者がすぐに実行して結果を確認できるような成果物が得られるように、チュートリアルを構成してください。その後、チュートリアルを続けて、さらに機能を追加します。
API の開発者はあまりにも密接に API の作業をしているために、まったくの初心者の目にはどのように映るかを忘れている可能性が濃厚です。このセクションの作業中は、一歩下がって初心者の身になって考えるように努めてください。
サンプル コードの作成
SDK Bridge でのアンケート調査の回答で一貫して指摘されたもう 1 つのポイントは、優れたサンプル コードの重要性です。開発者は、既に機能することがわかっているコードで作業し、その後そのコードを変更したり、機能を追加していくことで、新しいプラットフォームについて学習します。ほとんどではないにしても、多くの開発者は、説明を読むよりも実際に作業する方が容易に理解できます。
おそらく、優れた運用コードを作成する方法は既にご存知だと思います。優れたサンプル コードと優れた運用コードには同様の部分もありますが、大きな違いもいくつかあります。一般に、優れたサンプル コードを作成する場合は、次のガイドラインに従ってください。
- 関連する情報はまとめる。
- 効率性や堅牢性よりも、明瞭であることが重要。
- 見た目のよい UI よりも、簡潔であることが重要。
上記のガイドラインをソフトウェアの特定の領域に当てはめ、サンプル コードと運用コードを比較してみるとよいでしょう。
プログラマならだれでも、値をハードコーディングすべきでないことを知っています。このような値は定数に変えて、これらを変更する必要が生じた場合に、容易に見つけることができる場所に置くようにします。
しかし、この原則は運用コードには当てはまっても、サンプル コードには当てはまりません。サンプル コードでは値をハードコーディングして、関連情報をすべてできるだけ近くにまとめるようにします。運用コードでの定石に従ってすべての定数をファイルの先頭で定義すると、それらの定数を使用するコード行を参照するときに、ファイルの先頭までスクロールして、その値を確認しなければなりません。このちょっとした動作が、思考の流れを止めてしまうことがあります。文字列、整数、16 進数値などの単純な値は、すべて使用される場所でハードコーディングします。
コメントは運用コードでもサンプル コードでも有用ですが、サンプル コードでは極めて重要です。すべてのクラス、メンバー、または関数の最初に、その内容と機能について説明するコメントを少なくとも 1 行追加します。特に回避策やそれに相当する例外的な処理を記載する必要がある場合、コード内でわかりにくい場所に必ずコメントを付けてください。このようなコメントは、必要に応じて数行にわたる長いコメントでもかまいません。完全な文章にし、言葉数が多くなることを気にしないでください。
一般に、コードの 5 行おき、または 10 行おきに少なくとも 1 行コメントを挟みます。ただし、このガイドラインにはいくつかの例外があります。紹介する内容に関係のないコード (API の結果の表示に必要な UI のコードなど) には、それほど多くのコメントは必要ありません。リファレンスに含まれるわずか数行のコードから成る小さなスニペットを書く場合、コメントがまったく必要ないこともあります。また、運用コード並みの非常に大きなサンプルを提供する場合は、コメントの行数を抑えた方が実用的な場合があります。
変数、クラス、メンバー、関数の名前は、運用コードでもサンプル コードでも、明瞭な名前にします。ただし、サンプル コードでは、明瞭であることが効率よりも重要なため、この考えを運用コードよりも厳密に当てはめます。長くて扱いにくい名前は運用コードでは問題になり得ますが、サンプル コードではわかりやすさが増すため、通常はその価値があります。最も小さな変数でも意味のある名前を付けるようにし、どれほど気持ちが動いても、"foo" や 1 文字の名前のような意味のない変数名は使用しないようにします。
オブジェクト指向プログラミングは、ソフトウェア エンジニアリングの最高の発明の 1 つです。オブジェクト指向プログラミングは、運用コードでは非常に望ましい手法ですが、サンプル コードでは、実際に望ましい手法とは言えないとわかったら驚かれるでしょうか。その理由は、オブジェクト指向のデザインでは機能が分散されるため、データと関数がグループ化されます。また、重複するコードを削減するために、継承が使用されます。しかし、優れたサンプル コードの基本原則の 1 つは、関連情報をまとめることでした。オブジェクト指向コードでは、関連情報がさまざまなクラスに分散される傾向があります。したがって、メソッドの機能を確認するために継承階層の中を検索しなければならない可能性があり、これは、時間の浪費と思考の流れの中断にしかつながりません。
もちろん例外はあります。API の中には、オブジェクト指向プログラミングでないと正しく機能しないものもあります。運用アプリケーション並みの非常に大きなサンプルも、オブジェクト指向デザインが必要になることが考えられます。ユーザーにとっては、可能な限り、必要な情報をすべて 1 つのクラス内で確認できる方が便利なことを心に留めておいてください。
優れたソフトウェア デザインの基本のルールは、機能を関数とメソッドにカプセル化することです。運用コードでは、このように処理することでよりわかりやすくなり、重複コードを削減できます。また、優れたサンプル コードでもこれは有効で、多くの場合、開発者が各自のコードに単純にコピーできるコード ブロックが得られるため、使いやすくなります。
時折、API に直接関係がなくても、サンプルを実行するために必要な、行数が多いコードがサンプル コードに必要になることがあります。この場合、開発者が無視しやすいように、このような API に関係のないコード行を 1 つの関数またはメソッドにカプセル化するのはよい考えです。
紹介する必要がある UI 機能が API によって特に提供されていない限り、サンプル コード内の UI 要素は可能な限り簡潔にします。UI コードはかなりの行数を占め、紹介する重要なコード行が目立たなくなる可能性があります。開発者は、サンプルの外観が洗練されているかどうかは気にしません。API のしくみを理解できればよいのです。
どうしても UI にかなりの行数のコードが必要な場合は、開発者が検索または無視しやすいように別途関数を用意してコードをまとめます。
また、運用コードでは適切に機能するために例外処理が非常に重要ですが、サンプル コードでは、関係のあるコードを目立たなくし、注意をそらす可能性があります。多くの場合、有効な解決策は、例外処理を用意せず、運用コードで処理が必要になる例外を示すコメントを残すことです。ただし、特定の呼び出しでは必ず例外処理と併せて実行した方がよい状況があり、このような状況では、その例外処理の正確なしくみを示すコード行を追加することをお勧めします。
図 1 は、C# を使用してソーシャル ネットワーキング サイトに REST 要求を送り、指定したユーザーに関連付けられているユーザーの ID を返す方法を紹介するサンプル コードから抜粋した関数の例です。運用コードでは、REST エンドポイントの URL は、定数として他の関連 URL と併せて保存されます。しかし、サンプル コードでは、開発者がこの情報を最も参照すると思われる場所に置き、関数内でその役割への関連付けを行うのが最適です。また、エラー処理は示されていはいますが、実装されていないことにも注意してください。簡潔にするため、この例では XML 処理が削除されています。
図 1 サンプル コードの例
/// <summary>
/// Returns an array of user IDs for users that
/// are connected to the specified user. Note that
/// this is a simple, synchronous way to obtain the data.
/// </summary>
/// <param name="userId">The ID of the specified user.</param>
/// <returns>An array of user IDs that are connected to
/// the specified user.</returns>
public int[] GetConnectedUserIds(int userId) {
// Create variable to hold the returned IDs
int[] connectedIds;
// Construct a URL using the userId and the authorization token
string url =
"http://webservices.contoso.com/users/connections?userid=" +
userId.ToString() +
"&token=" +
authorizationToken;
// Create the Web request using the url
HttpWebRequest request =
WebRequest.Create(url) as HttpWebRequest;
// Get the response
using (HttpWebResponse response =
request.GetResponse() as HttpWebResponse) {
// Read the response XML
StreamReader reader =
new StreamReader(response.GetResponseStream());
string xmlResponse = reader.ReadToEnd();
// Process XML to extract user IDs for connected users
// and responseStatus
...
if (responseStatus != "ok") {
// Handle errors here
...
}
reader.Close();
}
return connectedIds;
}
リファレンス
リファレンスは、通常、大量の API ドキュメントで構成されます。クラス、メンバー、関数、XML 要素などのそれぞれに、それがどのようなものであり、どのように使用されるかについて詳しく記載する必要があります。少なくとも、リファレンスには次の項目を含めます。
- 簡単な説明
- パラメーターと戻り値の説明
- 開発者の役に立つ重要な解説
時間と予算に余裕があれば、次の情報を追加します。
- キャッチする必要がある例外
- 他の関連する概要またはリファレンス トピックへのリンク
- サンプル コードのスニペット (理想的には、作成済みのサンプル コードからの抜粋)
優れたリファレンス ドキュメントは、全体を通して一貫したスタイルがあります。スタイルのガイドラインが既に存在する場合もありますが、多くの場合は、自分で確立します。図 2 に、簡単な説明を記述する際の一般的なガイドラインを示します。
図 3 に示した Microsoft .NET Framework の Button クラスの説明を例にこのガイドラインを考えてみましょう。これは、MSDN の SDK ドキュメントから直接抜粋したものです。
図 2 リファレンス ドキュメントのスタイル
種類 | ガイドライン | 例 |
クラス | "を表します" などの語で締めくくります。 | "ユーザーの写真アルバムを表します。" |
メソッドと関数 | 動詞で締めくくります。 | "指定した領域の連絡先の数を返します。" "ビデオを一時停止します。" |
プロパティ | 名詞を使用するか、"取得します" または "取得および設定します" などの動詞で締めくくります。 | "ユーザーのタスク。" "ユーザーのタスクのコレクションを取得および設定します。" |
イベント | "のときに発生します" などの句で締めくくります。 | "サーバーからの応答を受信したときに発生します。" |
XML 要素 | 名詞句を使用します。 | "市区町村の郵便番号。" |
ブール値 | ブール値のプロパティの場合は、"~かどうかを示します" で締めくくり、メソッドや関数に対するブール値の戻り値の場合は、"~かどうかを返します" で締めくくります。 | "コントロールが表示されるかどうかを示します。" "2 つの領域が交差するかどうかを返します。" |
図 3 リファレンス ドキュメントの例
クラスまたはメンバー | 種類 | 説明 |
クラスの説明 | クラス | Windows ボタン コントロールを表します。 |
Button コンストラクター | コンストラクター | Button クラスの新しいインスタンスを初期化します。 |
Focus | メソッド | コントロールに入力フォーカスを設定します。 |
Visible | プロパティ | コントロールとそのすべての子コントロールが表示されているかどうかを示す値を取得または設定します。 |
Click | イベント | コントロールがクリックされたときに発生します。 |
Web API
この数年間で Web API の数は急速に増えているため、Web API がローカル API とどのように違うかを考えてみる価値はあります。SaaS (Software as a Service: サービスとしてのソフトウェア) が一般的なビジネス モデルとなりつつあり、自社システムから直接サービスを使用したいという得意先の要望を企業は敏感に察知しています。つまり、サービス プロバイダーは、ユーザーが呼び出せるパブリック API を用意する必要があります。
(用語に関する注意事項: ここでは、"ローカル API" という語を使用して Web 以前に存在していた通常の API を表しています。技術的には、この API はリモート プロシージャ コールになり得るため、その場合はローカルではありません。また、Web API はクライアントと同じコンピューターであるサーバーから呼び出される可能性があり、その場合はローカルです。しかし、ほとんどの場合、Web API は HTTP などの標準のプロトコルを使用し、リモートで使用され、他の API はローカルで使用されます)。
Web API は比較的新しいため、ドキュメントのスタイルについての標準はありません。Web API ドキュメントの質は実にまちまちです。適切に編成され情報が完全に網羅されているものもあれば、ごく最小限の情報が Wiki に投稿されているだけの場合もあります。Web API のドキュメントを執筆する場合、各企業ではどのように API のドキュメントを執筆しているかを調べ、参考にできる優れたテンプレートを見つけるとよいでしょう。たとえば、音声およびメッセージング アプリケーションのプラットフォームである Twilio には、すばらしい REST ドキュメントの例があります (twilio.com/docs を参照)。そのうちに、業界標準として数点の有効なテンプレートが確立されることを願っています。
ある意味、Web API のドキュメントはローカル API のドキュメントよりも重要です。これは、Web API のしくみを理解するために Web API を試してみるのが難しい可能性があるためです。たとえば、呼び出しを実行できる回数に制限 (割り当て) がある、試用すると運用システムに影響する可能性がある、サーバーの負荷が高くなるタイミングなど特定の条件をエミュレートすることが困難であるといったことが考えられます。
前述のとおり、開発者はサンプル コードに大きく依存しています。Web API のメリットの 1 つは、プラットフォームや言語に依存しないことですが、残念ながら、これはサンプル コードを作成する場合は作業が増えることを意味します。Python、Ruby、Java、C# などでサンプル コードを作成することが考えられます。そこで、ユーザーにとって最も重要で、最もよく使用し、注力している言語を特定するようにします。
Web API に一般に使われる 2 大テクノロジは、SOAP と REST です。SOAP には定義形式 (Web サービス記述言語: WSDL) があり、これはリファレンス ドキュメントの足掛かりとしては非常に便利です。一方 REST には定義形式はありません。サンプルの HTTP 呼び出しと XML または JSON ファイルは、しくみを示すうえでは SOAP でも REST でも有用ですが、十分ではありません。したがって、サンプルの後に、各要素とそのデータ形式を示す表を用意します。
たとえば、パラメーターを文字列として記述するだけでは不十分かもしれません。処理できる特殊文字はあるか、長さに制限はあるか、などを考慮する必要があります。XML 要素が日付であれば、日付の形式を指定します。時刻であれば、タイム ゾーンを指定する必要があります。
また、エラーがどのように処理されるかも説明する必要があります。これは、API がサポートする形式ごとに異なる場合があります。API が HTTP 応答コードを使用してエラーにフラグを付ける場合、このことをドキュメントに記載します。エラーのドキュメントでは、エラーが発生する理由と、問題の解決方法を説明します。
Web API では認証が必要になることがよくあり、これについても詳しくドキュメントに記載する必要があります。開発者が API キーを必要とする場合は、キーを取得するための詳細手順を必ず提供します。また、Web API は HTTP を基盤に作成されていることを忘れないでください。HTTP は信じられないほど多機能なプロトコルです。キャッシュ、コンテンツ タイプ、状態コードなど、ドキュメントに記載する必要がある HTTP 関連の情報がある可能性があります。
Web API は新しい API で、いまだにドキュメント執筆の最適な方法を模索している段階にあります。標準化が、今後数年以内に行われることを期待しています。
公開
ここまでは内容について説明しましたが、ドキュメントを公開して開発者が参照できるようにすることも必要です。概して、開発者は PDF などのフラット ファイルではなく、Web ベースでハイパーリンクが設定されたドキュメントを望んでいます。ドキュメントを Web に公開する方法にはいくつかあります。
API が小さければ、単純に HTML ファイルを作成するのが最も簡単です。CSS を使用して自社の Web サイトと外観を合わせるようにします。
Wiki は、より複雑な API に対応できる構造を備えています。また、他のツールやサーバーにアクセスしなくても、その時々で、容易にドキュメントの更新や追加を実行できます。さらに、Wiki のグループ作業機能を利用すれば、ユーザーも含めてチーム全体がドキュメント執筆に参加できます。ただし、Wiki を適当に用意して、開発者やユーザーがドキュメントを執筆することを願うのは、API ドキュメントの実用的な方針とは言えません。
たとえば、PHP ベースの MediaWiki (mediawiki.org/wiki/MediaWiki/ja) や PERL ベースの TWiki (twiki.org、英語) など無料のオープン ソースの Wiki エンジンがいくつか提供されており、API ドキュメントにもよく利用されるようになっています。
Madcap Flare などの商用ドキュメント ツール (http://www.xlsoft.com/jp/products/madcap/index.html) や Adobe RoboHelp (http://www.adobe.com/jp/products/robohelp/) は、主にエンド ユーザー ドキュメントに使用することを目的としていますが、API ドキュメントにも簡単に応用できます。商用ドキュメント ツールには、情報を入力するための簡単な UI があり、Wiki よりも洗練された外観が得られます。これらのツールでは、同じソースから Web ドキュメントとフラット ファイル ドキュメントの両方を生成できます。
PBworks (pbworks.com、英語) および MindTouch (http://developer.mindtouch.com/Deki_-_Japanese) などのコラボレーション サービスも API ドキュメントに利用されています。Wiki のコラボレーション機能に加えて、これらのツールでは、ホスティング、より詳細なアクセス管理、スクリプト機能など、追加機能が提供されています。これらのサービスは、通常、商用の場合はサブスクリプション料金が必要です。
まとめ
優れた API ドキュメントは、プラットフォームの採用と、会社が受けるサポート要請数の削減に大きく影響します。上司を説得して、適切なスキルを備えたテクニカル ライターを採用できるようであれば、そうしてください。しかし、それができないようなら、この記事のガイドラインに従ってください。
ドキュメントには、概要、基本操作のヘルプ、サンプル コード、リファレンスを含めます。概要では、必ず、プラットフォームを採用すべき理由を説明します。チュートリアルをまとめて、開発者が基本操作を習得できるようにします。サンプル コードは、明瞭かつ簡潔であることを主眼とします。また、運用コードと同じコーディングの原則には必ずしも従いません。リファレンスは、詳細で一貫性があるようにします。Web にドキュメントを公開する場合は、さまざまなツールを利用できます。
それでは、執筆に取り掛かりましょう。
Peter Gruenbaum は、物理学者としてスタートしましたがソフトウェア開発者に転向し、Tablet PC、拡張現実、CAD、手術シミュレーションなど多岐にわたるテクノロジに携わってきました。テクノロジと執筆に対する思いを融合すべく SDK Bridge LLC を設立し、テクノロジについての執筆と教育を行っています。
この記事のレビューに協力してくれた技術スタッフの John Musser (ProgrammableWeb) と Eugene Osovetsky (WebServius) に心より感謝いたします。