仕様の一覧の書き方

基本的な考え方

仕様の一覧のヘルプページでは、設定項目や一定条件における制限など、仕様に関する情報を網羅的に伝えます。

ユーザーは疑問を解消するためにページを訪れるため、上から通して読まなくても目当ての情報を見つけられることが大切です。

同じ粒度の情報が一覧性高く、網羅的に並ぶ状態を目指してください。

仕様の一覧では、最新の情報が網羅されていることが重要なため、情報が不足してしまうとヘルプページとしての価値が落ちてしまいます。

仕様の変更にあわせて、定期的にメンテンスが必要になることを見越して、扱う情報の範囲を判断してください。

仕様の一覧に関するヘルプページは、以下のセクションを組み合わせて構成します。

#	要素	内容	必須
1	タイトル	何の仕様についてどんな情報がまとまっているか	○
2	リード	何の仕様についてどんな情報がまとまっているかを一文で説明する	○
3	本文	表もしくは平文を用いて情報を羅列する	○

扱う情報によって、表を用いた表記と箇条書きを用いた表記を使い分けてください。

項目ごとに説明する条件が同じ、かつ、その条件が2つ以上ある場合には表が適しています。項目が並列で表示され、情報を見比べやすいというメリットがあります。

特に、同じ条件で各項目を見比べたいという読み手の要望がある場合は表が適しています。

例：A〜Cの権限がそれぞれ「作成」「編集」「削除」の操作をできるかどうかをまとめたい場合、以下のように権限と操作の対応を表にすると、わかりやすくなります。

項目ごとに説明すべき条件が揃わない場合や、共通する条件が少ない場合は平文での説明と箇条書きが適しています。平文の場合は、項目ごとに見出しを作成し、情報を構造化することを意識しましょう。

見出しが追加されることで、目次で情報を探しやすくなるというメリットも期待できます。