エンジニアが考える、情報対象性の高い資料作成に重要なこと


  [自ブログ](https://blog.hedrall.work/posts/doc-creation)からの引用です。
  
  ## はじめに

もともと情報対称性は、金融などの市場における情報の偏りによって売り買い双方の意思決定に不公平が生じる「情報の非対称」から来ています。そのため、主なポイントとしては以下があります。

- 透明性の確保
- 公平なアクセス
- 文書化の徹底

一方で、今日多くのTech企業が自社文化の一部として情報対称性を大切にしていますが、ここでいう情報対称性の価値は、本来の意味とは少し異なってきます。

- コミュニケーションの改善
- 効率的な問題解決
- 透明性と信頼関係の向上

つまり元々の意味では
情報が公開され公平にアクセスできることが重要であったのに対して、
テック企業でいう情報対称性では、
情報がうまく伝わった結果、何らかの価値を創出していることが重要になっています。

「帰るまでが遠足」である様に、「価値創出するまでが情報対称性」なので、単に情報を公開するだけでなく**伝わって初めて情報対象** と言えます。

本記事ではこの価値観を前提に、情報対称性を向上させるために必要な事柄を整理していきたいと思います。

## 考察する情報

単に情報といっても様々なものがありますが、
本記事では**開発チーム内**で扱う文書に関して検討します。

具体的には
- OKR, KPI, プロジェクト計画
- プランニング、要件定義、仕様
- 設計、ADR、テストスペック
- 運用ルール、手順書、マニュアル

などです。

逆に、経営資料など広範囲なもの、実務との直接的な関連性の弱いものは除外して検討します。

[//]: # (4象限で整理すると)
[//]: # (- 範囲: 全体 ~ 開発チーム)
[//]: # (- 実務との関連性: 高い ~ 低い)

## 伝わりやすい情報とは？

これまでの経験上、伝わりにくかった資料の特徴から逆説的に、整理してみます。

- 明確である
  - あやふやで不明確な情報は理解することが難しい
  - 内容に一貫性がある
- 構造化されている
  - 何がどこに書いてあるかわかる
  - 全体の俯瞰が容易である
- 受け手の期待値と一致している
  - タイトルやディレクトリと内容が一致している
  - 欲している情報は理解しやすい
- 理解に必要なコンテキストが、受け手のコンテキストと一致している
  - 全てを言語化することはできない。知識量の差によって暗黙知部分は必ず存在する

## 情報の質を高める

`伝わりやすい情報とは`であげた観点を踏まえて、 以下の2点の粒度で対応方法を検討します。

1. 資料群全体の構成
2. 資料単体の内容

### 1.資料群全体の構成

資料の管理ツールには主に

- Wiki型 (backlog, qiita team, esa)
- ファイル型 (google drive, confluece, notion)

などがありますが、いずれにしても無秩序に資料が散らばった状態では情報が伝わりにくくなります。
そのため、資料群全体の構成をうまく構造化していく必要があります。

では、どの様に整理するのが良いか？ですが、**情報の凝集度**を高めるべきと考えています。

例として、プログラムを書く時になぜわざわざファイルを分割するのかというと、モジュール化、つまり意味的な凝集を構成することで保守性を高めるためです。
膨大な資料であるプログラムコードの整理と全く同じことが、資料作成に関しても適用できると考えています。

**凝集度が低い**状態とは、**同じ内容が分散している**状態であり、その場合の主な問題は以下の通りです。

- どの資料みたら良いかわからず、欲しい情報にだどりつけない
- 全体像の俯瞰が難しく、内容を理解するのに時間がかかる (たくさんの文章を読む必要がある)
- 同じ内容が複数の資料に分散しているため、内容の修正が大変

この様に、情報の凝集度が下がると情報対称性の阻害につながります。

#### どのくらいの粒度で資料を分解するか？

オブジェクト思考プログラミングでは、単一責任の原則 (Single Responsibility Principle) という考え方があります。これは、クラスやメソッドは一つの責務を持つべきであるという考え方です。

資料作成でも同じ様な観点を持つことは重要です。資料の持つ責任を明確にすることで、Whatが明確になったり、必然的に情報の凝集度を高めることができます。重要なことは**異なる情報を混在させない** ことです。

以下に主な観点を整理してみます。

- カテゴリ
  - システム、運用、設計、労務
- 想定読者
  - 共有している背景情報が異なるので、内容の粒度が変る
  - ex) イメージ
    - 個人 > エンジニア > 開発チーム員 > サービスのセールス・CS > 全社向け
- 更新頻度
  - ex) 要件 vs 設計 vs 製品仕様
- 寿命
  - 永続的な資料 vs 一時的な資料 vs 中間生成物としての資料
- 内容の確度
  - 検討内容 vs 確定事項
- 想定筆者

箇条書きでまとめてみましたが、つまりは資料を分割する時に「なぜ分割するか？」のモチベーションになりうる事柄をまとめたにすぎず、これらはみなさんが普段自然と実践していることかもしれません。
ただし、場合によっては見落される観点もあると思うので、今一度適切な粒度で分割されているか再考する際に活用いただけると思います。

上記の観点で凝集度の高い状態を実現するには以下の2つのプロセスが必要になります。

- 1.凝集度の低い資料を分解する
    - **観点が異なる**情報が混在している資料を**観点**ごとに分割する
- 2.**観点**ごとにグループ化する
    - 資料同士の繋がりを明確にする
    - 親記事に子記事をリンクして階層を整理する (主にWiki型)
    - ディレクトリを活用して、分類する (主にファイル型)

### 2. 資料単体の内容

#### 明確にする

曖昧性のある内容だと、理解するのに時間がかかったり人によって解釈が変わるためにうまく情報が伝わっていかないことがあります。

そのため、記述から読み手が正確な理解をえられるか？をよく推敲していく必要があります。

例えば、ある指標の計算方法を文章化する際に、以下のような点があると、むしろ資料が混乱を招くことがあります。

- 定義(前提条件)に抜け漏れがある
- 数式が間違っている
- ロジックが最適でない

もし抜け漏れなど不備の可能性が消しきれない場合は、どの部分に曖昧性が残っているのか明記しておくことで読み手は頭を整理できます。そのほか、図や表を用いたりして説明すれば、イメージを明確に共有できます。

また、以下の様な記述を混在させると曖昧性が高まる危険性があります。

- 確かな情報 vs 予想
- 決定事項 vs 検討中の内容
- 個人的感想 vs 客観的事実

この中から執筆している文章の期待値にふさわしい観点を主要な観点として統一するのが望ましいと思われます。

例えば、
要件定義書の中に「検討中」の内容が多かったり、 運用ルールに個人的意見が書かれていると理解にばらつきが出てしまいます。

もし、主要な観点以外の観点が含まれる場合は、明示的に切り分けておくと混乱が少なくなります。

#### 構造化する

資料群全体の構成を整理することで、ある程度この資料に書かれる内容は絞られていますが、
さらに、1つの資料の中でも情報の場所や、構造、重要な事と詳細な事などの区別が簡単につく様にします。

例えば、

- アジェンダを整理する
- 重複なく記述する
- 事柄の親子関係を階層化する
- 背景情報など、補足的な説明は明確に切り出す
- 自分用のメモは別の場所に書く

などです。

イメージですが、構造化すると下記の様に認知負荷を軽減できます。

1. 雑然とした状態
```markdown
- 1 > 1-1 > 1-1-1
- 2 > 1
- 1 > 1-1
- 2
- 1 > 1-1 > 1-1-2
- 2 > 1
- 1 > 1-1 > 1-1-1
- 1
- 2 > 1
```

2. 整列する
```markdown
- 1
- 1 > 1-1
- 1 > 1-1 > 1-1-1
- 1 > 1-1 > 1-1-1
- 1 > 1-1 > 1-1-2
- 2
- 2 > 1
- 2 > 1
- 2 > 1
```

3. 重複を排除する
```markdown
- 1
- 1 > 1-1
- 1 > 1-1 > 1-1-1
- 1 > 1-1 > 1-1-2
- 2
- 2 > 1
```

4. 階層化する
```markdown
- 1
  - 1
    - 1
    - 2
- 2
  - 1
```

この様に、構造化は読み手側の認知不可を減らすメリットもありますが、書き手側が更新する際にも管理がしやすくなります。

#### 認知負荷を下げる

大量の文章で埋め尽くされた資料に出会うことがありますが、文章だけの表現には問題があります。

- 平面的に事実が並び、構造化しづらい
- 不用意な接続子、修飾語など、冗長な言い回しが増え、雑音が増える事で認知負荷が増す
- 文章内のエンティティの関連性を理解するのに、読解の必要がある
- 読み返す時に、もう一度文章を読む必要がある

そのため基本的なことですが、以下のような工夫が推奨されます。

- 箇条書き
  - 文章力が不要
  - 構造が明確になる
- 表(Table)
  - 必要な情報へのリーチと一覧性が圧倒的に高い
- 図
  - 視覚情報に高密度に情報を整理できる
  - メンタルモデルとして整理しやすい

もし、文章が増えてしまう場合は、内容の理解に曖昧な部分があるのかもしれません。
本質的に重要なポイントを抑えられていたり、メンタルモデルとして理解が構造化されていれば、適切な表現方法の選択がやりやすくなります。

## 主なアンチパターン

### 書きっぱなし

書いた当初は完璧と思われた資料も、活用して読み返されるうちに問題点に気づいてくることがよくあります。
長く利用される資料は、プログラムと同じ様にリファクタリング(整理整頓)が繰り返し行われるべきです。

これには二つの価値があります。

1つは単純に資料が読みやすくなる事です。
もちろん、時間は有限なので費用対効果を検討する必要はありますが、一方で自身を含む読者の認知負荷の改善に対するインパクトは過小評価されやすいと感じます。
情報対称性の意義を考慮し、効果を想像しながら濃淡をつけて取り組むと良いと思います。

2つめは文章の構成力が向上することです。
プログラマもリファクタリングを繰り返す事でだんだんと綺麗で保守性の高いコードを書けるようになります。
文章を書く時も同じで、最初から読みやすい文章を構成する事はできません。
こういったソフトスキルは日々の振り返りプロセスが重要になりますので、気づいたタイミングでより良い構成や表現を探して修正していくことが重要です。

### ソースをそのまま共有する

議事録やブレスト(発散)の内容をそのまま共有することは避けるべきです。情報は多い方が伝わるというのは誤解です。
ソースがそのまま残っていても、議事録を見た人が参加者の思考をトレースすることは難しいですし、だからこそ、そのMTGで同期的なコミュニケーションの時間をとっていたはずなのです。
構造化する中で、議論した問題に関する重要な点や、当初見えなかった隠れた構造などの再発見もあるはずなので、一度構造化する時間をとってから共有することは双方にメリットがあります。
もちろんアーカイブとしてソースをそのまま記録しておくのは問題なく、読み手は概要を理解した上で、気になった点を深掘りしていけると効率がよくなります。

### 全部入りの資料を作成する

情報が分散することの負を解消するために、多くの情報がまとめられた資料(wikiのトップ)の様な記事を作成することがあります。
この記事がうまく整理されていれば問題はありませんが、気をつけないと雑然とした情報群をただ1つの資料に集めただけで、むしろ読者を情報の洪水で飲み込んでしまいます。

情報量が多い場合は、まずは全体像を俯瞰できるような情報の整理が先決です。
端的に構造を示す為には、まとめ記事自体はリンク集+リンク先の概要説明としておき、情報全体のマップとして機能させることが望ましいと考えています。

## まとめ

DX企業でエンジニアとして働いてきた経験から情報対称性の実践方法を整理してみました。
個人的にはプログラミングは特別な作業ではなく、情報の整理の1工程にすぎないと考えているため、資料作成まで含めてより良いアーキテクチャを模索していくことがプロダクト価値に繋がっていくと考えています。

また、実践していく中で気づいた点をupdateして行ければと思います。