はじめに
株式会社ビットキーに入社してから1年9ヶ月が経過しました。
最近は、QAのナレッジを会社のアセットとするため、ドキュメンテーションに取り組む機会が増えています。
本記事では、筆者がドキュメンテーションを行う上で心がけているテクニックをご紹介します。
この記事を読むことの効果
- ドキュメンテーションのテクニックを知ることができる
- 読み手の気持ちに寄り添ったドキュメントを作成できるようになる
- 伝わるドキュメントが作成できることにより、情報の浸透性が高まる
ドキュメンテーションとは
情報を文書化することを「ドキュメンテーション」といいます。
分かりやすいドキュメントを作成することで、チームに以下の効果をもたらします。
- 情報を共通の認識にできる
- 個人の知識量に関わらず、再現しやすい環境を作れる
- 抽象的な概念を具体化できる
- コミュニケーションコストが下がる
このように、ドキュメンテーションの能力は、どの場面においても役立つ汎用性の高いスキルといえます。
ドキュメンテーションに必要なマインドセット
ドキュメンテーションに取り組む上で、必要となるマインドセットを3つ定義しました。
1. 「共感」を大事にする
伝わりやすいドキュメントを作成するには、読み手を想像し、共感することが大事です。
2. 「心地よさ」を追求する
参照していて心地いいドキュメントを作ることで、情報が定着しやすくなります。
3. 「Less is More」を意識する
「少ないほうが豊かである」という考えを示した言葉です。シンプルにすることで、重要な箇所が際立ちます。
1.「共感」について
ドキュメントを作成する際は、読み手を想像し、共感するように心がけています。
共感することで、読み手の「集中力」と「好奇心」に配慮できるからです。
「集中力」に配慮する
ドキュメントの内容を理解するまでにかかる負荷を「認知コスト」といいます。
認知コストが高いドキュメントは、解読に労力がかかり、読み手の集中力を妨げます。
反対に認知コストの低いドキュメントは、負担なく読むことができ、読み手の集中力を妨げません。
認知コストを下げるため、筆者は以下のことを意識しています。
色を使いすぎない
色は心理に訴えかけるため、伝えたいことのイメージを示唆することができます。
ですが、配色が多すぎるとイメージが曖昧になります。
そこで筆者は、色の上限を「3色まで」としています。
その際、色に以下の役割を割り当てます。
原色を使わない
原色は強い色であるため、目が慣れず読み手の負担となります。
また、コントラストの強い色を組み合わせると「ハレーション (目がチカチカする現象)」が起こり、視認性が下がります。
視認性を上げ、読み手の負担を減らすためにも原色は使わないようにします。
余白を作る
文字や表示物の間隔が窮屈であると、読み手に煩雑な印象を与えます。
そこで、文字や表示物の間に余白を作ることにより、参照してほしい箇所を負担なく注視できるようにします。
表示物を減らす
表示物が過剰であると、読み手は注視する箇所を見失いやすくなります。
そこで、過剰な要素を精査して削減します。
以下は、過剰になりうる要素の例です。
- 文章
- ()や【】などの約物
- 色
- 固定行
- 表のカラム
「好奇心」に配慮する
伝えたいことは、自身が思うように相手へ伝わりません。
内容について多くの場合、読み手の好奇心が書き手よりも高くない状態にあるからです。
読み手の好奇心に配慮せず、ドキュメントがひとりよがりな状態であると、情報が伝わりにくくなります。
情報の伝達率を上げるため、筆者は以下のことを意識しています。
共通の用語を使用する
あらゆる概念は、用語によって具体化できます。
ですが、一般的でない用語や、専門的な用語を使用すると、読み手に誤った認識を持たせてしまう恐れがあります。
そのため、読み手の属性をイメージして使う用語を決定する必要があります。
状況によっては、用語を定義し、ドキュメント内で展開する手段を検討します。
▲ 専門的な用語をドキュメント内で展開した例
既存の構成に似せる
人には「慣れ親しんだものをより受け入れやすい」という性質があります。
これを「認知容易性」といいます。
この性質を踏まえ、筆者はNotionでドキュメントを作成する際、以下の工夫をしています。
- 「親アイテム」と「サブアイテム」機能を使い、ドキュメントの構造をテストツールやPCにある「ディレクトリ」に似せる
- 「ボタン」と「ID」機能を使い、ドキュメントの操作感を「JIRAの起票」に似せる
▲ PCの「ディレクトリ」に似せた例
▲ 「JIRAの起票」に似せた例
2. 「心地よさ」について
情報を定着させるため、参照していて心地いいドキュメントの作成を目指します。
筆者は以下を意識しています。
「デザインの4大原則」を使う
デザインには4つの原則があります。「近接」「整列」「反復」「対比」です。
これらの原則を使うことでドキュメントが整い、読み手は内容に集中することができます。
「視線誘導」を意識する
視線は表示物のレイアウトによって誘導できます。これを「視線誘導」といいます。
レイアウトを工夫し、読み手の視線を誘導することで、伝えたいことが明確になります。
具体的に以下を意識しています。
▲ 横組の文を読むとき、視線は「Z型」に動く
▲ ジャンプ率の高い表示物を優先して見る
「ジャンプ率」を意識する
表示物の大きい部分と小さい部分の比率のことを「ジャンプ率」といいます。
表示物のジャンプ率によって、読み手に与える印象が変化します。
また、目的によって適しているジャンプ率が異なります。
ジャンプ率が高いと、訴求力がありますが、読み飛ばしが発生しやすくなります。
一瞬で情報を伝えたい広告や、WEBページに適しているといえます。
ジャンプ率が低いと、視線が誘導されず、読み飛ばしが発生しにくくなります。
仕様書など、正確に読んでもらいたいドキュメントに適しているといえます。
「画像優位性効果」を意識する
人には、文字よりも画像や図を含む情報を記憶しやすいという性質があります。
これを「画像優位性効果」といいます。
また、画像や図を取り入れることで、情報の定着性を上げるだけではなく、イメージを一瞬にして伝えることができます。
3. 「Less is More」について
「Less is More」とは「少ないほうが豊かである」という考えを示した言葉です。
この言葉の通り、情報を必要最低限にし、可能な限りシンプルにすることを心がけています。
シンプルにすることで、重要な箇所が際立つからです。
筆者はドキュメントの作成後、最後の仕上げとして、削減できる箇所がないかの確認を行います。
終わりに
私たちが無意識に良いと感じるデザインには、様々な工夫が隠れています。
これらの工夫に注目し、テクニックとして認識することで、ドキュメンテーションスキルの向上に限らず、学ぶことや、他者へ伝えることが容易になるのではないでしょうか。
以上、ドキュメンテーションを行う上で心がけているテクニックをご紹介させて頂きました。
Discussion