ドキュメントについてつらつらと考えたこと

はじめに

エンジニアリングをする中で「時間を取って後でドキュメントを書こう」と思う瞬間がある。
これは自分もたまにやってしまうことで、特にゾーンに入っている場合だったり、ガッと実装してしまったほうが早い場合だったりに起きているように思う。
しかしながら当然、ドキュメントを書かないことによる弊害というのも存在することは明白で、短期的に見るとスピードが出るのは間違いないのだが、長期的（と言っても状況によっては1ヶ月、2ヶ月と全然遠くない未来だったりする）に見て様々な問題が発生する。

ドキュメントがないことに対する弊害

例えば新機能の開発について考えてみる。

ドキュメントを整備しないまま実装した場合、実装した瞬間から「動いているものが正しい」状態になってしまう。仮にリリース前に仕様変更があった場合、ドキュメントがないと動いているものから仕様を読み解き、修正する必要があるかもしれない。
例として契約プランと契約年数で割引率が変わるロジックに手を加える場合、マトリクス表を一個書いておけば仕様把握は一瞬ででき、「パターンBをB'に変えたいんです」といった話がスムーズに行えるだろう。
だがマトリクス表がない場合はどうだろうか？どういう条件で分岐しているかコードリーディングした上でまとめ、どこをどうするか検討する必要が出てくるかもしれない。
この場合のコストは実装時にドキュメントを書くよりも工数が発生するように思うのは僕だけだろうか。

例えば新メンバーが加入した場合について考えてみる。

ドキュメントがないままオンボーディングするとなると毎回アーキテクチャやデータベース、システム構成について図を使って説明する必要があるだろう。
既存の仕様についても同様で、コードリーディングするかテストコードから挙動を追う必要があるかもしれない。
この辺りのキャッチアップは非常に時間がかかるもので、サービスが成長すればするほど、ドキュメントがない場合の工数は指数関数的に増えていくと思っている。
あるいはドメイン知識が浅いままに既存機能の修正を行った場合、考慮漏れが検知できず思わぬエンバグにつながるおそれもある（それを回避するためにコードレビューがあるが、コードレビューも万能ではないので）。

例えば既存機能の修正について考えてみる。

言わずもがなだが、ここがドキュメントがない弊害が一番大きく出る部分だと思う。
既存の仕様の把握、ドメイン知識に対する理解、考慮漏れによるエンバグや思わぬデグレードなど、リスクを考えると枚挙にいとまがない。
クリティカルでない軽微なバグであればまだ許容できるかもしれないが、決済周りや個人情報周りだとサービス信頼性にもつながりかねないため、非常に難しい部分だと思う。
最悪なのが実装者が全ての仕様を忘却していた場合や、退職などによって社内にいない場合だ。
こうなると口伝ですら伝えられなくなるので、よりリスクが大きくなるのは言うまでもないことと思う。

ではどうするのか

これはあくまでも個人のやり方なので、絶対の正解ではないということを事前に書いておく。

自分が実装に入る場合、実装前に機能のER図やフローチャートや状態遷移図、画面遷移図などからイメージを見える形に落とし込むようにしている。
これによってレビュアーの負荷が減るだけでなく、共通認識も生まれるので実装しようとしているものに対する理解が深まるし、ドメイン知識という観点からもレビューしやすくなると思っている。
特に後々ハマりそうなケースによる処理の分岐部分だったり、条件に応じた判定だったりはマトリクス表を作って認識に差異がないかを確認するようにしている。

実装者が仕様について一番理解しているタイミングは「実装後」ではなく「実装中」だと思っている。
そのタイミングで面倒くさがらず、ドキュメントを書いてから実装に移るよう習慣づけることができれば多少なりとも「ドキュメントがない問題」は解消していくのではないだろうか。
エンジニアリングにおいてコーディングしている時間が全てではなく、むしろその前段の仕様設計部分に時間がかかるものだと思うので、せっかくなら成果物が誰かの役に立つ形で作っていければいいなと思っている。
ここで言う誰かとは自分も含まれており、3ヶ月後の自分が忘れても思い出せるように書いている。そう、僕がドキュメントを書くのは他の誰でもない自分のためなのだ。

このやり方にしてからというもの、実装時の手戻りが減ったような感じがあるし、コードレビューも通りやすくなった気がしている。
「コーディングするフェーズではすでに自分の実装するものの完成形が見えており、後は手を動かすだけ」というのが理想形の一つだと最近考えるようになったため、この習慣は今後も続けていきたい。

この際に気をつけるべきは、見栄えを優先するあまり完璧なものを作ろうとしないことで、完成度6割でもいいので自分の脳内メモを形にすることだ。
まずは自分のために、メモからでもドキュメントを残す癖を実践していけるといいのかなと思う。

でも・・・

ドキュメントは更新されない限り腐っていくものなので、究極的には「ドキュメントがなくても理解できるような実装」になっていることが望ましいのかなとは思っている。
また肥大化したドキュメントをどう整備していくかだったり、参照性が低いと誰も読まなかったり、ドキュメントがフラグメントしていって同じような情報が色んなところに散らばったりといった課題もある。
ドキュメントを腐らせないようにする工夫の一つとしてtblsは最高のアプローチの一つだと思っているので、皆さんもどんどん導入していきましょう（突然の宣伝）。
それに留まらず、今が一番いいやり方であるとも思っていないため、今後もよりよい方法を模索していきたい。

追伸: 決定事項や意思決定は必ず残すことを心がけるといいかなと思います。