ドキュメントを書く目的を整理してみた

こんにちは。フロントエンドエンジニアの辻です。

弊社 Gaji-Labo では、各メンバーのノウハウを共有する Wiki の策定を進めています。社内では職能横断 Wiki や標準 Wiki と呼ばれています。
異なる職能の知見を集合して、チークワークの強化・コミュニケーションの円滑化を図るのが目的です。
はじめは手が止まる事もありましたが、現在ではいくつか Wiki が策定され、活用も始まりつつあります。

こうした取り組みの中で、「 Wiki、もとい、ドキュメントを書く目的」を私なりの言葉で整理できてきました。
今回はそれを紹介していきます。

ドキュメントを書く目的 = 知識の積集合を形成する

そもそも、ドキュメントを書く目的とは何なのでしょうか？
様々な目的があると思いますが、私は「知識の積集合を形成する」事にあると考えています。

そして、知識の積集合を形成するためには、下記の2ステップが必要です。

1. 書き手と読み手の知識量を同量にする
2. 書き手と読み手の認識を共通化する

いきなり抽象的な話が出てきて、何が何やらですよね。。
これからベン図を使って整理していきます。

1. 書き手と読み手の知識量を同量にする

はじめに「1. 書き手と読み手の知識量を同量にする」についてです。

下記のベン図をご覧ください。
左側に書き手の知識量。右側に読み手の知識量の2つの集合を配置しています。

それぞれの集合の大きさですが、「書き手の知識量を100として、読み手はいくらか？」を想定して書きます。
今回は読み手の知識量 = 約60としています。

さて、読み手がドキュメントを読み始めました。
そうすると、読み手の知識量が少しずつ増えていき…

読み手がドキュメントを読了すると、おおよそ書き手の知識量と読み手の知識量が同量になりました。
これにて「1. 書き手と読み手の知識量を同量にする」は達成です。

読み手の想定

上記のベン図ではシンプルすぎるので、もう少し具体例を考えてみます。
あるシステムに関するドキュメントを作成するとしましょう。
さっそく執筆に取りかかる…前に、読み手のペルソナを想定してみます。

例えば、ドキュメントの読み手が同僚のエンジニアだとしましょう。下記のようなペルソナを想定してみました。

• 読み手：同僚のエンジニア
• 知識量：60/100
• ドキュメントを読む目的：ある機能Xの改修のため、その周辺技術のみ把握したい。

知識量から鑑みるに、この同僚のエンジニアはある程度システムに精通しているようですね。
…であれば、ドキュメントの概要欄はシンプルにまとめて良いでしょう。もしかしたら、箇条書きでも事足りるかもしれません。
機能Xに関する解説文は、より丁寧に書いた方が良いでしょう。
周辺技術に関する参考文献のリンクも添えると、より理解が進みそうですね。

また、別の読み手を想定してみます。

• 読み手：はじめてシステムに触るパートナーエンジニア
• 知識量：0/100
• ドキュメントを読む目的：まずはシステムの全容を把握したい

このパートナーエンジニアは、はじめてシステムを触る方ですね。
…であれば、はじめから丁寧に解説したドキュメントを用意するのが良さそうです。
他にも用語集やよくあるQ&Aなども用意すると、より理解が進みそうですね。

このように読み手のペルソナを想定してみると、ドキュメントに書くこと・書かなくとも良いことが見えてきます。
上記はあくまで例であり、読み手が一人に限定される事はまずありません。複数人に読まれる事を想定してドキュメントを書くのが常です。
ですので、実際は読み手の母集団の最大公約数となるペルソナを想定していきます。

2. 書き手と読み手の認識を共通化する

次に「2. 書き手と読み手の認識を共通化する」を見ていきます。

書き手が苦労してドキュメントを作成して、読み手へ提供しても、書き手と読み手で共通認識がなければ、意味がありません。
人間同士の認識を合わせる事は非常に難しく、書き手だけが頑張ってなんとかできるものではありません。

そこで書き手が読み手も巻き込んで、認識を共通化するフェーズが必要です。
ドキュメントのレビュー会や読み合わせ会を実施したり、共に用語集やよくあるQ&Aを作成すると良いでしょう。

「2. 書き手と読み手の認識を共通化する」もベン図を使って、見ていきます。
下記は、「1. 書き手と読み手の知識量を同量にする」を達成後のベン図です。
この状態から…

ドキュメントのレビュー会や読み合わせ会を経て、少しずつ書き手の知識量と読み手の知識量を重ね合わせていきます。

最終的に、書き手と読み手の知識が重ね合わさった状態 = 知識の積集合が形成されました。
ここに至って、はじめてドキュメントの真価が発揮されます。

認識の共通化の例

「2. 書き手と読み手の認識を共通化する」についても、具体例を考えみます。
（少々悪例ですが、分かりやすさを優先して掲載します。）

上記は、点P（Px, Py）を点Q（Qx, Qy）を中心に、反時計回りにθ度回転させる数式です。
（数式の理解は不要です。「こういう数式があるんだな」ぐらいに思っていただければと。）

上記の数式を JavaScript のコードに書き起こして、ドキュメントも書いてみました。
ドキュメントに「どの向きに回転するか」が記述されていない点に留意してください。

const rotate = (P, Q, t) => {
 const rad = t * (Math.PI / 180)
 const c = Math.cos(rad)
 const s = Math.sin(rad)
 return {
   x: c * (P.x - Q.x) - s * (P.y - Q.y) + Q.x,
   y: s * (P.x - Q.x) + c * (P.y - Q.y) + Q.y,
 }
}

▼ドキュメント
rotateは二次元座標上の任意の点Pを、別の任意の点Qを中心にθ度回転させる関数です。
第一引数Pと第二引数Qは座標であり、形式は{ x: 数値, y: 数値 }です。
第三引数tは度(°)です。
戻り値の形式は{ x: 数値, y: 数値 }です。戻り値は、第一引数Pとは別の新規オブジェクトとして生成され、返却されます。

さて、上記のドキュメントを読んだエンジニアのAさんとBさんは、このように考えました。

• Aさん「rotate関数は、第一引数Pを第二引数Qを中心に反時計回りにt度回転させる関数なんだな。」
• Bさん「rotate関数は、第一引数Pを第二引数Qを中心に時計回りにt度回転させる関数なんだな。」

おっと！ AさんとBさんとで回転方向の認識に相違が発生してしまいました。
では、解説文に「反時計回りに回転する」と記述した方が良いでしょうか？

• Aさん「別にいらないよ。ドキュメントの文章から反時計周りの回転行列だと分かるよ。ソースコードにも sin や cos が記述されている事からも察しがつくしね。」
• Bさん「いやいや。ドキュメントの文章では反時計回りにも時計回りにも解釈できちゃうよ。回転する向きも書いたほうが親切だよ。」

ふむ。いずれも主張もよく分かります。

この「反時計回りに回転すると記述した方が良いか？」という問題は、突き詰めていくと「ドキュメントにどこまで詳細を記述するべきか？」に行き当たるでしょう。
答えは人それぞれと思いますが、私は「書き手と読み手で認識を共通化できているか、が判断基準になる」と答えます。
つまり、「書き手と読み手で認識を共通化できていない = 知識の積集合の補集合に位置する要素があるなら、ドキュメントに明記すべき」と考えています。
ベン図で表すと、下記の赤丸が認識を共通化できていない点です。

もし、書き手と読み手の間で既に認識の共通化ができているなら、詳細な解説は冗長になる可能性があります。
反対に、書き手と読み手の間に認識の共通化ができていないのなら、詳細な解説は読み手にとっての助け舟になります。

先程の JavaScript コードとドキュメントの例になぞらえると、ドキュメントを読んで「ああ。これは回転行列だな。」と思い至るAさんにとって、さらなる詳細な解説文は不要でしょう。
反対に、Bさんにとってはドキュメントに詳細な解説があれば、数式の詳細を知らずともrotate関数を扱えるようになります。

ここまで「2. 書き手と読み手の認識を共通化する」の例を見てきました。
この例もあくまで例であって、現実の状況はもっと複雑です。
書き手が知っていて、読み手が知らない知識はたくさんあるでしょうし、その逆もありえます。
さらには、書き手も読み手も意識していない暗黙知の明文化に頭を悩ます時もあるでしょう。

ドキュメントは書き手の独力に頼るのではなく、書き手と読み手の双方でブラッシュアップして、認識を共通化する事が大切ですね。

まとめ

以上、私なりにドキュメントの目的を整理して、まとめてみました。
ドキュメントを書こうとすると、網羅性・正確性・整合性の担保や文章力などのテクニックに目が行きがちでしたが、いったん立ち止まって目的を再考してみると、思わぬ気付きにつながりました。

これを機にドキュメントの品質向上、ひいては、職能横断 Wiki を通したチームワークの強化までつなげていく所存です。