はじめに
最近、案件先で調査資料やマニュアルなどのドキュメントを作成する機会が多く
「体系的にドキュメント作成について記載された本とかないかな」と思っていました。
そんな自分にとって、うってつけの書籍を見つけまして購入しました。
そして先日読み終えたので
この場をかりて、どのような事を書いていたのか簡単にまとめていこうと思います。
ドキュメントの種類
ドキュメントの種類としては主に以下の3つがあります。
- 概念や手順を説明する（説明型）
ex 要件定義書・バックログ・仕様書・マニュアル・作業手順書 - 知見や活動を報告する（報告型）
ex 報告書・論文・技術ブログ - 意見や提案を伝えて相手の行動に促す（説得型）
ex 企画書・提案書
ドキュメントを書く上で大事なこと
ドキュメントを書く上で大事なこととしては主に以下の3つがあります。
- 必要な情報を正しく得られる
- 効率よく理解できる
- 不快さがなく、ポジティブに受け止められる
必要な情報を正しく得られる
- 曖昧さを廃し、明確な文章を書く
- できるだけ具体的に書く
- 誤解なく読める文章を書く
例えば「画面の表示が速い」ではなく「画面が5秒以内に表示される」のように記載するようにします。
効率良く理解できる
- 要点を先に伝える
- どこに何が書いてあるかをわかりやすくする
- 話の流れを整理し、理解しやすくする
- 簡潔で読みやすい文章で書く
- 必要な情報だけを書く
残念ながらほとんどの読み手は最後まで事細かに読んでくれないので
書き手としては流し読みされることを前提にして、それでも必要な情報が伝わるように
書く努力が必要です。
（そのためには、上記に列挙したものを意識すれば良いのではないかと思います。）
不快さがなく、ポジティブに受け止められる
- 肯定形で書く
- 信頼される表現で書く
読み手としては否定形より肯定形の方が印象は良いみたいなので
意識して書いていただければ良いのではないかと思います。
ただし禁止事項を伝えるときは敢えて否定形で書いたほうが強く伝わりますので
この場合は、否定形でも良いかと思います。
ドキュメントとプログラミングの共通点
ドキュメントとプログラミングにも似ている点がいくつかありますので
何点か記載しようと思います。
最初の設計が大切
設計に不備があって開発が遅れてしまったという経験をお持ちの方が何人かいらっしゃるかも知れません。ドキュメントも同様で文章を書き始める前に行う設定の工程は非常に大切です。
何故ならば、設定を怠ると何を書いてるかよく分からない文章になり
読み手も書き手も苦労することが多いからです。
内容を表した関数名（見出し）を付ける
関数を設定する時は、相手が分かりやすい関数を付けることを意識されることが多いと思います。
（ex ユーザ情報を取得する関数なのでget_user(id)と名付ける。）
ドキュメントも同様で書かれている内容が端的に分かりやすい見出しを付けることが大切です。
見出しから内容を推測できれば、要点を掴んで詳細を読めるので、内容が頭に入りやすくなります。
1つの関数に1つの役割を持たせる
1つの関数が複数の役割を持つと、プログラムの読みやすさやメンテナンス性が低下します。
関数のコードが複雑化して可読性が落ちるだけでなく関数の再利用性も低下します。
またテストや、バグの原因特定もしづらくなります。
ドキュメントも同様で1つの見出しに1つのテーマを持たせることが原則です。
1つの見出しの中に複数のテーマを詰め込むと、見出しの中で言いたいことが分かりづらくなり
分かりやすさが低下します。
コードを共通化する
プログラミングにおいて、コードを共通化すれば効率や保守性の面で効果が非常に高いと思います。
ドキュメントも同様で同じことを複数の箇所に書かないことが大切です。
特にマニュアルでは共通する記述を1箇所にまとめて、必要な箇所から参照リンクを貼ることで
時間や労力を節約できるだけでなく記述の修正も楽になります。
ただし過度な共通化は可読性を損なう点も、プログラミングとドキュメントの双方に共通します。
ドキュメントに参照リンクが多くなりすぎると、読み手にとって読みづらくなります。
そのため効率性・保守性と可読性のバランスを考えることは非常に大切です。
ドキュメントを作成する5つのステップ
ドキュメントを作成する上で以下の5つのステップを順番にすると
非常に良いドキュメントが作成できると思います。
- 読み手とテーマを選定する
- テーマを分解する
- ドキュメントの構成を組む
- 文章の構成を組む
- 文を書く
以下、順番に説明していきたいと思います。
読み手とテーマを選定する
1つ目のステップは、誰に何を伝えるかというドキュメントの目的を明確にすることです。
そのために「読み手の事前知識・読み手の目的・読み手の立場や役割」の3つの軸で読み手を理解し
ドキュメントのターゲットとする読み手を絞り込みます。
絞り込むことによって、ドキュメントのテーマも自ずと絞り込まれると思います。
テーマを分解する
2つ目のステップは、テーマを分解することです。
テーマをドキュメントの構成へ落とし込むために以下のように分解していきます。
テーマ
↓
サブテーマ
↓
話題
ここでは、テーマを「なぜ・何を・どうやって」の3つの要素で分解します。
テーマをこの3つに分解することで、ドキュメントが論理立った構成になり
伝えたいことに対して読み手はきちんと納得を得られるようになると思います。
ドキュメントの構成を組む
3つ目のステップは、ドキュメントの構成（アウトライン）の組み立てです。
先ほど分解したテーマをもとにアウトラインを組み立てます。
テーマを適切に分解し、それをアウトラインに反映することで必要な情報を探しやすく
情報を理解しやすいドキュメントになります。
また本文で何が書かれているか、本文で何が言いたいかかが分かる見出しになるように
工夫すれば、なお良いと思います。
文章の構成を組む
4つ目のステップは、文章の構成の組み立てです。
話のまとまりを作成するパラグラフを意識して、話の筋を作ります。
話のまとまりとは、「言いたいこと」と「理由・説明・具体例」のセットのことを指します。
両者をセットにすることで、一つ一つの話題に対してきちんと読み手の納得を得ながら
話を進めていきます。
文を書く
5つのステップは、分かりやすい文を書くことです。
ここまでくれば、何を書くかは決まっていますので
あとは一文一文を分かりやすく書くだけです。
こちらに関しては先ほど「ドキュメントを書く上で大事なこと」の章で挙げましたので
そちらを参考にしていただければと思います。
さいごに
もしドキュメントを書くことに苦手意識をお持ちの方が、本記事を通じてその意識が和らいだと感じていただけたなら、非常に嬉しく思います。