わかりやすいドキュメントを書くには 〜 全体像を把握できることが重要

はじめに

エンジニアなら誰でもたくさんのドキュメントを読むことになります。
その中にはわかりにくいドキュメントも少なからずあると思います。

自分はわかりにくいドキュメントは「全体像が掴みにくい」ことが多いと感じています。

そこで、ここではわかりやすいドキュメントを書くための方法を「全体像を把握できるようにする」という視点でまとめてみました。

また、最後に具体例としてQiita APIドキュメントでわかりにくい点の指摘と改善をしてみました。

ここで扱うドキュメントの種類

ここでは仕様書やリファレンスマニュアルといった類のドキュメントを想定しています。

Qiitaの投稿やブログの記事といったものでも共通する部分は多いのですが、これらには他にも重要な要素があると思うので、ここでは扱いません。

わかりにくいドキュメント=全体像が掴めないものが多い

先ず、わかりにくいドキュメントとはどんなものでしょうか？

自分が今まで見てきた中で多かったのは、次のようなものです。

• いきなり詳細から始まっている
• 目次がない
• ページに見出しがない

目次もなくいきなり詳細から始まっていると、そのドキュメントにどんなことが書かれているのかが最後まで読まないとわかりません。
ページに見出しがない場合も、そのページに書かれていることを全て読まないとわかりません。

これらに共通している問題点は「全体像が掴みにくい」ということです。
全体像が掴めないと、いくら詳細が丁寧に書いてあってもなかなか頭に入ってきません。

文単体の質より全体のわかりやすさが重要

「わかりやすいドキュメントの書き方」などでググると「である調・ですます調を揃える」「主語・述語の関係に気をつける」など、文の質を上げることに着目している記事を多く見かけます。

中には誤字・脱字がないものがわかりやすいドキュメントだと書いているものもあります。

こういった文単体の質を上げることはもちろん大事なのですが、ドキュンメトを判りやくする偽には全体象を把握できることの方がよリ需要なことです。

全体像を把握しやすくする為には

では全体像を把握しやすくする為にはどうしたらいいでしょうか？
基本はわかりにくいドキュメントの逆を考えることです。

• 冒頭に概要を書く
• 目次を付ける
• 見出しを付ける

冒頭に概要を書く

一番重要なのは、詳細に入る前に概要を書くことです。

「本書はxxxの仕様を記述したドキュメントです。」のような定型文を書くだけでは意味がありません。
詳細の理解に役立つもの、事前に知っておくべきことなどを書きます。

具体的には次のような事を必要に応じて書きます。

• xxxとは
  • 対象システムや機能の説明を簡潔に書く
• 図・一覧
  • ドキュメントの説明対象が一望できるもの
  • システム構成図、画面構成など
  • 画面仕様書なら画面一覧、API仕様書ならAPI一覧など
• 動作環境・前提条件
• ドキュメント自体の概要
  • ドキュメントの目的
  • 対象読者
  • 記述範囲、ここでは扱わないもの
  • 他に読んでおくべきドキュメント
• 用語定義

目次を付ける

目次を付けることでそのドキュメントに書かれている事が一覧できるので、全体像を把握しやすくなります。
また、必要な時に読みたい箇所を素早く参照できるようになります。

エクセルやパワーポイントでもボリュームのあるドキュメントでは目次を作っておいたほうが親切です。

エクセル

目次用のシートを作成して各シートへのリンクを作ります。
シート名だけでなく各シートの説明や付加情報も書いておくといいです。

パワーポイント

ドキュメント全体の目次と、各セクション毎の目次を作成します。
目次というより概要を箇条書きにするイメージです。

• ドキュメント全体の目次
  • セクションの一覧を箇条書きで
• 各セクション毎の目次
  • セクションで説明する内容を箇条書きで
  • 全ページのインデックスにする必要はない

wikiなどのWebドキュメント

自動生成の目次だけでもいいですが、ボリュームのあるドキュメントの場合は、説明を付けたり論理的にグルーピングした目次を自分で作るとわかりやすくなります。
技術書やOSSライブラリのリファレンスマニュアルなどで良く見かける書き方です。

例：

• Django ドキュメント

見出しを付ける

パワーポイント

見出しを省略してしまうと、そのページで何を説明しているのわからなくなります。
各ページに必ず見出しを付けるようにしましょう。

• 説明が複数ページにまたがる場合の見出しは「xxx(1/3)」のようにする
• セクションの区切りでは見出しのみのページを挿入する

エクセル

必ずシート名をデフォルトから変更するようにしましょう。

具体例：Qiita APIドキュメント

最後に、Qiita API v2ドキュメントを具体例として取り上げて見ます。

ちょっとだけ上から目線で書きますが、決してQiitaを批判することが目的ではないのでご了承ください。

残念なところ

• API一覧がない
  • 初めて見た時にどんなことができるのかが最後まで読まないとわからない
  • APIの詳細を見たい時に素早く参照することができない
• Qiita:Team用APIも混在して書かれている
  • いきなり「グループ」「プロジェクト」という単語が出てくるので「Qiitaにこんなのあったっけ？」ってなる
• 認証状態(未認証/認証済)によって使えるAPIの違いがわからない
  • なんとなく予想はできるけど、詳細を見ても明記されていない

概要を書いてみました

ここに挙げた問題点は、概要をまとめることで解決できるので書いてみました。

Qiita API v2 の概要

各セクションは次のような意図で書いています。

• Qiita APIとは
  • 対象を簡潔に説明することで、初めての人でも理解しやすくする
• 認証状態とユーザータイプによる違い
  • 使えるAPIが違うことを説明
  • この後の一覧でグルーピングの意味がわかるようにする
• 認証認可
• モデル一覧
• API一覧
  • 全機能が一望できるようにする
  • 目次として機能するようにリンクにする
  • 興味のないAPIを読み飛ばせるようにグルーピング

まとめ

このように、全体像を把握できるようにすること、特に概要を書くことがドキュメントをわかりやすくなる上で重要だということがわかったと思います。

• 冒頭に概要を書く
• 目次を付ける
• 見出しを付ける

改めて見直してみると、ドキュメントを書く上での基本中の基本でしたね。