ドキュメントに固執せよ

どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい．

ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである．

非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです

— 画力・博士号・油田 (@bd_gfngfn) June 3, 2022

ドキュメントに書く内容の必須項目

或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメントを書く場合に必ず入れるべき内容は何だろうか？ 端的に言えば，以下に挙げるような，論文のAbstractとIntroductionにあたる部分が必要だと考える：

• 背景： 前提的説明．文書全体にわたって関わる用語の定義なども行なう．
• 目的： なぜこのシステムが必要だったのか？
• 要件： このシステムは大域的な構造として何を実現しているのか？
• 外部仕様： このシステムはどのように使えるものか？ どんなAPIをもつか？
  • Web APIなどであれば，エンドポイントを叩く簡潔な具体例なども添えられているとよいかもしれない．

例えば，もし仮に腕時計というシステムを初めて実装したとして，その腕時計についてドキュメントを書くなら以下のような具合だろう：

• 背景： “1日の中で時間がどの程度進んでいるか” を定量化した，時刻という概念がかつて創出された．1日を24分割した単位を時間，さらに1時間を60分割した単位を分と呼ぶ．時刻は，1日の中の何番目の時間の何番目の分にあたるのかで表す．いずれも0-originで表される．
• 目的： 外出中を含めどこにいても現在の時刻を知りたいため，腕時計を製作した．
• 要件： 腕時計は，目で見ればいつでも現在の時刻が読み取れる小さな装置であり，内蔵電池により一定の速さで回転する機構に接続された針状の部品により各瞬間にそのときの時刻を図形的に提示する．本体の装置に小さなベルトのような部品が付随していて，軽量で小さいために腕に装着して携帯することができる．指し示す時刻の精度は，1日の経過で±1分ずれる程度．
• 外部仕様：
  • 装置の盤面上を短針と長針が回転し，これらがそれぞれ時間と分の目盛を示すことで現在時刻を表現する．ただし，時間の目盛は12分割で刻まれており，半日で1周する．
  • 側面にあるつまみを回すと，盤面が指す時刻を手動で補正することができる．

これらの情報が必要なのは，こうした情報なしにただ実装されたシステムのみに対面させられた人はそれを何らかの文脈の中に位置づけることができず，したがって今後開発が必要になりそうなことの検討などが容易にはできないからである．腕時計という概念を知らされずに実物の腕時計に対峙させられた人は，それが何を目的とした道具でどう使えるものなのか，すぐにはわからないに違いない．何日か眺めたりしているうちに，どうやら一定の速さでゆっくり回転している2つの針がついた装置らしい，というところまではわかるかもしれないが，そんな再発見をする必要はないし，しかもいざ腕時計の改善を依頼されたとしてもそもそも用途がおぼろげにしかわからないので何をすれば改善なのかということから実感がもてない．初見者がこうした困惑に陥るのを防ぐには，単にドキュメントによってごく手短に目的・要件・外部仕様といった概要だけ最初に知らされていればよいのである．

また，注意すべきなのは，腕時計の内部でどのように歯車が組み合わされているのかなどの内部仕様・内部実装の話は初見者向けのドキュメントに書くべき必須項目には含まれないということだ．人間は自分の実装したものについて説明するとき，ともすれば何が解決困難な課題だったかとかどこに工夫を凝らしたのかといった “苦労話” を詳細にしたくなってしまうけれども，そういう話を初見の読者にいきなりしても何も伝わらない．それは概要をよく理解していて内部仕様も既に多少理解している人だけに伝えればよいことだ．そうした内容は，想定読者を絞ることを明記して別のドキュメントに記載するのがよい．或いは，概要を把握した状態でコードを少し眺めれば自然にわかってくるような内容なら，そもそもドキュメントにする必要もないかもしれない．

ともかく，ドキュメントで何よりも先に伝えなければならないのは「なぜつくったのか」「何を実現しているのか」「どう使えるのか」である．読者が追加で著者に質問することなくこれらを読み取れないドキュメントは事実上ドキュメントではないと言ってもよいかもしれない．

ドキュメントを書く時に大切にすべき法則

読めるドキュメントを書くのはかなり知的体力を要することである．少なくともシステムを実装すること自体よりもずっと難しい．プログラムは不整合について型検査器が指摘してくれたりするし，壊してしまえば既存のテストが通らなくなるので気づけるが，ドキュメントはそうはいかない．なにしろ，自分が既にかなり詳しくなっている対象について，まだそれを知らない人がどんな説明を見れば理解を後押しされるか想像して書かねばならない．

だが，少なくとも以下のことを意識して書けば，読めるドキュメントとして最低限の足切りは突破できそうだ：

• 想定読者を明らかにし，要求する前提知識を文書全体で一貫させる．
  • 例えば，或る箇所では読者がTCP/IPを知らない前提で書いているのに，別の箇所では輻輳制御について何も説明なく書いているようなドキュメントは一貫していない．
• 可能な限り結論から書き，大枠→詳細という順番にする．
  • ボトムアップに説明して伏線回収するような書き方をすると，伏線回収が来るまでの間読者に（最終的に何が言いたいのだろう）と集中と忍耐を強いることになる．読者は集中力を切らし，離脱してしまうかもしれない．
• 用語を定義する箇所は太字にするなどして，初出の場所をわかりやすくする．また，定義が広く共有されていない用語やシステム独自の概念を表す用語について，読者に要請する前提知識の範疇にない限りは説明なく登場させたりしない．
  • 別のドキュメントにその用語の定義があるなら，そのドキュメントへのリンクを張るなどするとよい．

ドキュメントに乏しいと何が問題になるか？

読めるドキュメントが不足していると，端的に言えばそのこと自体がチーム内での理解の共有を大きく妨げる．もし「わからないことがあれば質問が来るからドキュメントはいい加減でも大丈夫だろう」と考えているなら，その思い込みはおそらくかなり危険だ．この危険性にはいくつかの理由がある．

何がわからないのかがわからない

既に腕時計の例で記載したが，読めるドキュメントが不十分だと，システムについて新たに理解しようとする人は今の自分が何を理解していないのか自体を把握できていない状況を抜け出せない．これがドキュメントに乏しいことによって引き起こされる最大級の問題である．前述のような「なぜつくったのか」「何を実現しているのか」「どう使えるのか」を満足に記載していないドキュメントもどきのドキュメントしかない状況では，まずシステムに込められた “世界観” が伝わらないのだ．

もちろん理想的には「これってそもそも何のためにつくられたシステムなんでしょうか？」などと根本的な質問を臆さずにできるとよい．だが，既にそのシステムについて造詣のある質問された側が，質問した側にとって良い回答をすぐに用意できるかにはそれほど期待できないかもしれない．人間は内部実装に詳しくなるにつれてソフトウェアの大域的な機能への意識を失って言語化しなくなってしまうように見受けるし，それはどこかに書き留めておかねばならない．書き留める経験を経ることで言語的に意識できるようになるのである．

さて，「何がわからないのかがわからない」状態からの唯一まともな抜け道は「既に詳しい人が能動的に概要を伝える」だが，もしそれが口頭で行なわれるなら新しい人が増えるたびに同じことをせねばならず，教える側が線型に時間と労力を消費する．質の良いドキュメントの形なら少なくとも読者人数の増加に対して執筆側の消費時間は定数なので，まずはドキュメントを整備すべきだ．その上で，最初のとっかかりを素早くするために要点だけ口頭で伝える，といったことをするとよさそうだ．

質問はコストが大きい

そもそも質問は莫大なコストを要する行為である．まず，ドキュメントが執筆者の行動をブロックしないのに対し，質問は同期的に行なわれねばならないという単純な制約がある．質問される側はそのたびに思考のコンテキスト切り替えをしなければならない．それ自体はあまり問題ではないかもしれないが，質問する側に「質問相手が別のことに集中しているかもしれないので質問していいか迷う」という負荷がかかる．

さらに，自分がまだ理解していない点が何なのか，質問者は正確に言及・記述しなくてはならない．口頭での意思疎通であれば口調で意味を制御できたり迅速に何度も応答しあうことで補正していけたりするが，特に文面によるコミュニケーションは厄介だ．口頭での発話以上に，人間は文面に対して裏の意味を読み取る癖がある．例えば「なぜAが良いと思ったんですか？」という文面は「普通に考えればBにするだろう，浅はかな奴め」というニュアンスを含んで発される傾向にあるので，理由を問うには適さないことが多い．純粋に理由を尋ねたい書き手は「この場合Bもありうるかなという気がするんですけど，Aにすべき理由って何かあったりしますか？」のような “裏の意味なんてないですよというメタデータ” を満載した表現を選び，邪推されるおそれを緩和する必要がある．テキストでの意思疎通に於いては，こうした “裏の意味の回避” という工面が厖大に蓄積することになる．COVID-19の影響下で望む望まらざるにかかわらずリモートワークが一般的となった現状では，特に文面でのやり取りの比重が増しており，ますますこうした負荷がかかりやすくなっている．

意思疎通の負荷を少しでも低減しようとして「心理的安全性」という概念が盛んに叫ばれるようになったが，想像するほど簡単に達成できるものではない．“仲良しチーム” になるのではなく，“相反する意見をぶつけ合っても根抵には相手への信頼がある” という状況をつくらねばならないからだ．

ついでに言えば，質問とは必然的に “自身の無知を晒す行為” である．意識的には「こんなことに関して自尊心を抱く合理的理由などどこにもない」と思っていても，“相手の許容範囲を超える無知を晒すだけになるかもしれないという不安” とは恒に隣り合わせを強いられる．こうした心理的コストにより気後れし質問自体が後回しになる傾向も全く無視できそうにはない．これもやはり「心理的安全性」によって緩和されうる課題ではあるが，そう簡単ではない．

そんなわけで，そもそも対人コミュニケーションというものは “厖大な知的体力と時間を奪われ，ペイロードではなくメタデータの比重が大きい，デフォルトでかなりの損害をもたらす営み” だ．こうした損失を上回るような実りある内容だけを対人で同期的にやり取りするのが工学的な態度だといってもよい．良質なドキュメントは，それを大きく緩和する役割を担える．全くドキュメントを整備せずに「わからないことがあったら質問してくださいね」と待っていてはいけない．

なぜドキュメントは書かれないのか？

ドキュメントが整備されない要因について，いくつか思いつくものを挙げてみる：

1. そもそも人間は或る対象，とりわけ自身が実装したものについて，チームとして理解が共有できているわけではないにもかかわらず，自分が理解できていれば満足してしまいがちなため．
   • 「何か困ったことになっても自分が取り組めるから大丈夫」と思い込んでドキュメント整備を後回しにしてしまう．そして永久に書かれない．実際は，困ったことが起きるのは自分の業務時間外かもしれない．自分以外が問題に対処せねばならないとき，そもそも問題に関わる部分がどこなのかさえ認識できないかもしれない．
   • 「誰かが困ったら自分に訊いてきて，そのとき自分が答えられるから大丈夫」と思い込んでしまったりする．実際は，前述の通りドキュメントの最低限の内容（なぜ必要だったのか，何を実現しているのかを簡潔に述べた記述）がなければ「何がわからないのかがわからない」という状態を容易には抜けられないので，そもそも質問が発生しにくい．
2. 制度に強制されないため．例えばシステムを実装しリリースしたことだけが成果と看なされ，そのシステムに関するドキュメントを整備したかどうかについてはほとんど問われない環境に置かれると，人間は必然的にドキュメントを書かなくなったり，或いはドキュメントを自分用のメモ程度のものと位置づけてしまう．
   • たとえ，缺陥のある評価制度に迎合することなく，属人性を排し持続的に開発可能なシステムをリリースし続けたいという高尚な動機に満ちた人物でも，スケジュールの都合で泣く泣くドキュメント整備を後回しにしてしまうことを恒には避けられないだろう．
   • これはマネジメントの制度的・構造的な問題である．しばしばステークホルダからの圧力によりエンジニアチームはリリースに関係しない作業をおざなりにしてしまうが，それはエンジニアリングの責務の一部しか全うしていない．例えば，『Clean Architecture』には「持続的に開発可能な状態を維持するための作業分の工数を設けるようにスケジュールを組み直してステークホルダにフィードバックするのも責務なのだ．そうした責務も引き受けることを怠れば，やがてリリースのサイクルは破綻をきたしステークホルダを苛立たせることになる」という旨が記載されている．
   • 極端な話，「レビューを通ったドキュメントを伴っていないリリースは成果ではない」と捉えさせるくらいの制度設計でもよいかもしれない．
   • 貴方がもし「別にドキュメント足りてないけど開発はなんとか成立している様子だし，制度として存在しなくても問題ないよね．ドキュメントの不足で開発ができてない人がいればその人が成長しないといけないだけ」と思うマネージャだとしたら，それは大変危ういと思う．要するに “作業者によるウェットで再現性のないマンパワーに過度に依存できてしまっている” 状況なのである．とりわけ日本に於ける組織の特色として「上層部が企てた大域的な計画に無理があっても末端の作業者が奴隷根性を活かしてなんとかバイブスを上げて乗り切ってしまうから仕組みづくりが行なわれないままになる」などという主張がまことしやかに語られたりするが，まさにその典型例が貴方のチームなのかもしれない．
3. ミクロ的には属人性が組織内での個人の価値に繋がってしまうことがあるため．特定の事柄を或る人しか知らないことによってそれに関する作業がその人しか行なえず，結果としてその人物が高く評価されることに繋がりうる．
   • やはり評価制度などでインセンティブを適切に設計しこうした可能性を防ぐ必要がある．
4. 他のタスクに時間を取られ，執筆時間を充てられないため．
   • 理想論を言えば，ドキュメントを書く時間がないと従事している人が感じる時点でマネジメントが部分的に失敗しているという側面があると思う．やはり，開発ワークフローやスケジュールの時点でドキュメントの執筆時間やそのレビューの時間を組み込んでおく必要がありそうだ．
   • 執筆ばかりに時間を取られてはいけないとはいえ，前述のドキュメントの必須項目くらいはそれほど時間をかけずに書けるはずだし，裏を返せば必須項目がそれほど苦労なく書けるシステムほど良いシステムだと言ってもよいかもしれない．
   • 第一，ドキュメントを十分書かなかったために将来生じるコストよりも今書くコストの方が遥かに低そうだ．執筆に要するコストを避けてドキュメントの整備を怠るのは，種芋を植えれば将来たくさんの芋を実らせるのに目先の利益のために種芋から食べてしまい将来の自分達の首を絞めているようなものだ．
5. ドキュメントを書いても読まれないと思っているため．
   • 自分が重い腰を上げてドキュメントを整備したのに読むべき人が読んでくれないという経験をすると「結局ドキュメントを整備するなんて徒労だ」と学習してしまうのかもしれない．だが，既に述べたように，読めるドキュメントを書くのは想像以上に難しい行為で，思うがまま書けば終わるようなものでは決してない．ドキュメントが読まれない場合は，原則としてドキュメント自体にまだ問題があると思った方がよいかもしれない．真っ先に「なぜつくったのか」「何を実現しているのか」「どう使えるのか」を端的に伝えているだろうか？ 結論を最初に述べて大枠→詳細の流れで書いているだろうか？ こうした執念深い内省やレビューを経てようやく読めるドキュメントが完成するのではないかと思う．
   • 一方で，読む側にもドキュメントに良くない点があれば提起したいという執念があるに越したことはない．結局，書いたドキュメントが読まれない問題を緩和するにはレビューという仕組みがあることが肝要だろうと思う．
   • ただ，とりあえず思い立ったら書いておくということで書かれた文書も何もないよりはずっと良いし，そういった行動を阻害してしまっては却って心理面で生産性を落としうるので，“レビューを受けるべきドキュメント” と “まだメモ書きの文書” がうまく共存できる仕組みが必要なのだろうとも感じる．

ドキュメント整備をどう開発ワークフローに組み込むか

正解はひとつではないと思うが，大枠としてこういった形でドキュメント執筆を開発ワークフローに組み込むとよさそうだという案を記載してみる．

まず，動機（≒目的）と対処とは別の文書にまとめると見通しが良いかもしれない．開発タスクには動機が大雑把に分けて2種類ある：

• 改善： 既に実装・運用されているものに問題点が見つかり，対処したい場合．
• 拡張： サービスとして新しい機能を実現したいなど．

そして，その動機に対する対処方法も大別して3種類ある：

1. 既存機能の修正
   • ロジック自体に不具合があることがわかったので修正する，実際のユースケースでの規模と実装とに乖離がありパフォーマンスが悪いので設定値を変更したりアーキテクチャを変えたりする，など．
2. 既にあるシステムへの新規機能の追加
   • HTTPの口が開いているシステムに新しいAPIを生やすなど．
   • 内部実装としては既存の実行パスに手が加わることも多い．
3. 全く新しいシステムの実装

改善の場合，問題点が見出された時点でそれを改善動機として文書に書き起こす．サーバで取得しているログやメトリクスなどを添付し，どのような現象が起きているか，それが何に支障をきたしているのかを記載する．拡張の場合，何らかの機能を実現したい主体にヒアリングし，何ができているとよいかという要望の1次情報を記載する．こうした文書は，NotionやConfluenceといったページ然とした仕組みではなく，しばしばTrelloやJIRAのようなタスク管理システムが記載場所を担っているかもしれない．文書を書いたら，これ自体はレビューされる必要がないが，問題意識の共有としてその文書を（エンジニアとは限らない）関係する人々に見せたりするとよい．

続いて，対処方法を検討して案が固まってきたら対処方法のドキュメントを書き始める．この時点ではまだ検討用のドラフトである．また，このドキュメントと改善や拡張の動機を記述した上記の文書は相互にリンクが張られる必要がある．ドキュメント側の「なぜこのシステムが必要だったのか？」という目的の項目は，そのリンクによって代えてよい．このドラフトには，上記の文書を作成する過程で得られた要請や要望などを要件に落とし込んで記載する．要件の確定は，既に動作しているシステムの都合を調査して折り合いをつけたり，他のチームが担当しているシステムの都合も勘案したりせねばならず，なかなか厄介なタスクである．要件が整ったら，まずこの時点でレビューを受けるのが良い．このとき，レビュアーは既存システムに詳しい人とあまり知らない人の両方を含むのが望ましい．なお，要件の勘案のためにはチームを横断したりしてさまざまな前提知識を出揃わせる必要があり，それはただでさえ執念を要する作業なのだが，それに加え既存システムのドキュメントが整っていないとここで大変時間を奪われることになる．

要件が確定したら設計に着手する．全く新たにシステムをつくる場合を除いて，設計はやはり既存システムの設計ドキュメントを参照したり，コードそのものを見たりして参考にし，どう拡張できるかを練り，ドキュメントに丁寧に記述する．どうしても複雑な変更となることが予期されるなら，実際に簡単にコードをいじって実現可能か確かめる仮実装を行なってもよい．ここでも，もし既存のドキュメントが低品質だったり不十分だったりしたら，システムの大域的な仕組みについてすら延々と実装を眺めて理解する羽目になったりして時間を浪費する．

設計をひとまず書き起こしたら，やはりレビューを受ける．レビュアーは要件をレビューした人々と同じでよい．曖昧な箇所があるとか，こうした考慮漏れががあるのではないかとか，この設計だと要件を充足しきれていないのではないか，といった指摘をもらいながら修正する．ここでレビュアーは（この文が何を言っているかはよくわからないけれども，単に自分が詳しくないのが原因だな）と気後れしてはならない．少なくとも想定読者に適合するレビュアーである限り，わからない点があってはならないのだから，むしろそれはドキュメントの質を向上できるよい機会である．どういう意図で書かれたものなのかわからないと積極的にフィードバックを送るとよい．ここで質問をしなければ，ドキュメント確定後に該当箇所を読んだ人がほとんど皆似たような疑問をもち，納得しないまま読むのを諦めてしまうか，あらためて質問せねばならないかの状況になる．勿論，結果的に確定後のドキュメントに不明瞭な記述が残っていて読んだ人から質問が発生してしまうのは止むを得ないし，その時点でドキュメントを改善すればよいが，最初からそうした可能性を減らすよう努めることを怠ってはならないだろう．

こうして設計が確定したら，本実装にとりかかる．ここからは一般的な開発どおりである．ただし，本実装に移った後に（あっ，あそこの設計若干まずかったな）と気づくことがあるので，適宜設計を修正し，レビュアーに簡単に了解をとる．軽微な設計の修正であれば，実装のレビューと同時でもかまわないかもしれない．

最終的にめでたく修正や新規機能がリリースされたら，ドキュメントをドラフトから確定の状態にする．既存システムの修正の場合は，施した修正に合わせてもともとあったドキュメントを訂正することも必要である．

というわけで，まとめると以下のような手順になる：

1. 動機を文書にまとめる．改善の場合は現状の問題点を，機能追加の場合は追加したい人による要望のヒアリング結果をそれぞれ記し，問題意識の共有としてその文書を関係する人々に見せたりする．
2. ドキュメントのドラフトを書き始め，1の動機の文書をもとに要件を定める．1の文書とここでつくるドラフトは相互にリンクを張り合う．特にドキュメント中の「目的」の項目は1の文書へのリンクで代用できる．
3. 2に記載した要件などのレビューを受ける．レビュアーには，既存システムについて造詣のある人とそうでない人を交ぜて割り当てる．レビュアーは，この時点でわからないことがあれば書いた人に積極的に質問する．
4. 3のレビューを通ったら，要件をもとに設計を練り，ドラフトに加筆する．複雑な設計にならざるを得ず妥当性に自信が持てない場合は，仮実装として既存システムの実装をいじったりしながら吟味する．
5. 4で記載した設計のレビューを受ける．レビュアーは3と同じ組み合わせ．レビュアーは設計の妥当性だけでなくやはりわからない記述について積極的に質問してドキュメントの不十分な点を洗い出す．
6. 5のレビューを通ったら本実装に移る．この過程で設計の不備が明らかになるかもしれないが，特に重大な場合は再度レビュアーに確認を取る．軽微な場合は実装のレビューと同時に確認を取ればよいかもしれない．
7. 実装がめでたくリリースされたら，ドラフトだったドキュメントを確定の状態にする．既存のドキュメントの修正や移植も適切に行なう．

やや机上の空論的な面もあるが，こうしたワークフローを長すぎないサイクルで回し，ウォーターフォール的にならないのが理想的であろうと思う．3と4，および5と6は，それぞれ或る程度並行できるかもしれない．

また，重要なのは，上にもたびたび書いたように既存のドキュメントがないと足枷になるということである．将来の足枷をつくらず，「既存ドキュメントが充実しているからこそ次の開発のドキュメントが手早く書ける」という好循環に入るためには，こうしたワークフローが必要なのではないかと思う．

そうは言ってもドキュメント整備の困難さはある

前節に掲げたようなワークフローがうまく回れば理想的だと思うが，まあそう一筋縄ではいかないであろうことも目に見える．大概は以下のような部分がネックになりそうだ：

1. システムに詳しくない人をレビューに割り当てる時間が取れない
2. 既にドキュメントに乏しい状態になってしまっているので，次の開発に関するドキュメントを整備するのが大変である
3. レビューがナアナアで素通りになってしまう
4. 更新が忘れられたドキュメントが生じて，何が現状を正確に反映している記述なのかわからなくなる
5. 後から見ると，ドラフトや検討資料なのか，或いは最終的に確定したドキュメントなのかの区別がつかないことがある

3, 4, 5については恒に起きうる問題である一方，1と2は既にここで言うところの悪循環に陥っていそうな状況である．どうやって脱却すればよいのだろう？ おそらく，ただでさえ失速している開発ペースの中に停滞してもよい時期を見つけ，遅れながらも地道にドキュメントを整備して挽回していく王道しかないのではないかと思う．上でも述べたが，エンジニアのチームは，リリースして顧客などに価値を届けることだけでなく，持続的な開発可能性を担保することも責務とせねばならない．どこかで一念発起して，とりわけ良いドキュメントを書ける人を何人か短期間ドキュメント整備専門の要員にし，各システムについて詳しい人から活発に聞き取りを行ないながら手分けして整備していくのが底上げと持続性向上につける薬になるのではなかろうか．もしとうとう手をつけられなくなったという時期がその後きてゼロから作り直すことになるのだとしても，ドキュメントを整備することで現状のシステムの全体像を把握し何がうまくいっていて何が微妙なのかを洞察として得られていれば，きっと作り直す時にも生きる資産になる．

或る程度技術的に解決する手段はないのか？

さて，前節で挙げた3「レビューが素通りになってしまう」，4「ドキュメントの追従が忘れられがち」，5「ドラフトなのか確定版なのか後から遡ると区別をつけにくい」といった問題について解決策の大枠を考えてみたい．これはどんなにドキュメントが充実していても起こりうる課題である．

端的に言えば，ドキュメントの執筆とレビュー自体が現状では人間の注意力に依存しすぎているためにこうした課題が生じる．対比としてプログラムの場合は変にいじって壊してしまった場合でも型エラーが報告されたり既存のテストが落ちたりすることによって不備に機械的に気づけるのだから，ドキュメントについてもこれに似た仕組みが確立できれば改善できそうだ．そこで思い当たるのが以下に挙げるようなソフトウェアである．

DEEP査読者 + マークアップ言語

これはかなり大雑把な概念だが，要するに深層学習などによって統計的処理を実現したソフトウェアが自然言語（と補助的なマークアップ）で書かれたドキュメントを人間の代わりに読み，どこで理解が詰まりやすい文面になっていてどのような理由でわかりにくいのかを報告するというものだ．似た先行事例としてはGrammarlyやRedPenなどが知られているが，これらをさらに発展させて文章を精査してくれるものにしたイメージである．こうしたソフトウェアがあれば，3の「レビューが素通りになってしまう」という問題は緩和できる．

ただし，たとえこうした用途のソフトウェアが著しく発展を遂げたとしても，人間には普通に理解できるのにDEEP査読者にはわからないという “偽陽性” があまりに頻繁に発生するなどして信頼されなくなってしまうおそれがあり，どのような “厳しさ” でチェックするかのバランスの見極めが本質的に難しい．

Doc Copilot

GitHub Copilotの文章版である．すなわち，ちょっと文を打ち込んだら「多分こういうことが言いたいんじゃないですか？」とサジェストしてくれるソフトウェアだ．こういった，事後的にチェックするのではなく生成の時点で手伝うというアプローチによって，執筆とレビューの負担を緩和できるかもしれない．

ドキュメント追従チェッカ

ドキュメントから別のドキュメントやソースコードに対して「このドキュメントはここの記述に依拠しています」というポインタを張っておき，張られた先のドキュメントや実装が更新された場合に「この記述は古くなったかもしれませんが，追従する必要はありませんか？」と元々の著者やレビュアーなどに通知する，という仕組みである．これで4「ドキュメントの追従が忘れられがち」が解消される．この仕組みは上記2つに比べれば技術的には大きな苦労なく実現できるだろうが，そもそもリンクを正確に張ること自体が難しいという問題に行き着いてしまい，問題が後退するかもしれない．

その他： ドキュメントシステム自体の機能

残っているのは5「ドラフトなのか確定版なのか後から遡ると区別をつけにくい」だが，これは結局ドキュメントシステムがドラフトなのか確定版のドキュメントなのかを区別する仕組みを持っていることにかかっていそうだ．或いは，それ専用の機能がないとしてもページ配置のツリー構造上ドラフトと確定版を別の場所に置いて扱っておくなどの単純な工夫でも案外対処できるかもしれない．

まとめ

かなり長くなったが，それだけドキュメントは大切だということを私は伝えたくなったということである．重要な点だけおさらいして結びとする．

• ドキュメントは「なぜつくったのか」「何を実現しているのか」「どう使えるのか」についての記述を含んでいなければならない．一方で，初見者に対していきなり内部実装の説明をもってくるべきではない．
• システムに関するドキュメントを書くのはとても知的体力を要する．しかし良いドキュメントが満たしている原則はあり，それに従うと最低限読めるものになる：
  • 想定読者を明らかにし，要求する前提知識を文書全体で一貫させる．
  • 可能な限り結論から書き，大枠→詳細という順番にする．
  • 用語を統一し，どこで定義されているのかわかりやすくする．
• ドキュメントに乏しい状況だと，初心者は自分が何をまだ理解していないのか自覚できない状況を抜けることができず，その状態では能動的に質問することも難しい．
• 質問はそもそも知的体力上も心理上も多大なコストを要する行為である．できるだけ双方向でない伝達手段であるドキュメントで済む方が望ましい．
• ドキュメントが書かれない要因はいくつもあるが，その中の高い割合は制度的・構造的にドキュメントを書くことが強制されなかったり評価されなかったりして生じている．マネジメントとしては，ドキュメントが積極的に書かれるように適切にインセンティブを設計しなくてはならない．
• 読むべき人がドキュメントを読んでくれないとき，それは原則としてドキュメント自体にまだ問題があるということだと考えた方がよいかもしれない．
• ドキュメント整備は開発ワークフローに大々的に取り込んで，要件や設計の各段階でレビューをしてもらうことで進めるのが理想的と思われる．
• 既存システムがドキュメントに乏しいために開発が遅くなり更にドキュメントも書かれなくなる悪循環は，制度設計を適切にした上でどこかで一念発起してドキュメント用の時間を設けて脱出するしかなさそうだ．
• 制度設計とは別に技術的に解決策する方法として，「DEEP査読者」「Doc Copilot」「ドキュメント追従チェッカ」という構想を挙げた．