リファレンス・トピックの書き方 <reference>

リファレンス・トピックは、プログラミング言語のステートメントの解説、ソフトウェアのアプリケーション・プログラミング・インターフェイス(API)の解説など、定型的な説明を書くために使用します。

リファレンス・トピックは、リファレンス情報だけを集めた独立した文書(例えば、リファレンス・マニュアル)に書かれる場合や、1つの文書の中で他の情報と分離された専用のセクションに書かれる場合があります。後者の場合、リファレンス・トピックは、タスク・トピックやコンセプト・トピックに関連付けられますが、常にタスク・トピックやコンセプト・トピックといっしょに読まれる訳ではありません。何かを理解する、あるいはタスクを完了するために、詳細な情報が必要になった場合にだけ、リファレンス・トピックが参照されます。

通常、リファレンス・トピックはランダムに読まれます。関連するトピックからリファレンス・トピックへジャンプして読む場合、読者に送られた何らかのイベント(例えば、システム・メッセージ)に対応するリファレンス・トピックを読む場合などがあります。このことを念頭に、以下の点に留意してリファレンス・トピックを書くべきです。

ヒント: プログラミング言語やAPIリファレンス・マニュアルの場合、リファレンス・トピックに書く情報は、機能仕様書に書く情報と同様になります。詳細設計に関係する一部の情報を除外することにより、機能仕様書の情報をリファレンス・トピックに流用できる可能性があります。