ドキュメントを書くことを拒絶するな

はじめに

ドキュメントは資産である。 ものづくりの仕事においては成果物と同等、もしくはそれ以上に価値がある。 だからドキュメントを書くことを疎かにしてはならない。

ドキュメントの分類

IT企業のエンジニアであれば、ドキュメントと言えば仕様書やミーティング議事録などは耳にすることが多いだろう。 聞き馴染みがない人もいるかもしれないがADR¹といったドキュメントも存在する。 これらのものを一括りにドキュメントと呼んでいるが役割が異なっている。 役割の違いから大きく二分することができ、常に正しい情報が記載され間違っていたり事情が変化したりした場合に都度更新するストック型のドキュメントとある時点における事実を記載するフロー型のドキュメントとに分けられる²。 前述したものでは仕様書はストック型、ミーティング議事録やADRはフロー型になる。

更新の要否を認識することでドキュメントを残すハードルが下がるだろう。 フロー型のドキュメントは基本的には更新しなくて良いのでとりあえず形として残し、後から何かを決めた当時のことを振り返ることさえできれば良いという意識で情報を残す。 ストック型のドキュメントは常に更新し続けなければならないが、一度作ってしまえば何かの変更の際に変更するのは細かな部分で良い。

このような更新の有無を徹底するためにはドキュメントの役割をはっきりさせ、そのドキュメントに必要な情報、不要な情報を認識する必要がある。 例えば仕様書においては現時点での事実のみが記載される必要がある。 その決定に至るまでの経緯や不採用となった設計などは別のドキュメントに記載し、仕様書に記載することがないようにしなければならない。

ドキュメントがもたらすメリット

ドキュメントは確かに最初こそ作るのが大変で、都度更新するというのもやや面倒に感じるかもしれないが、情報がドキュメント化されていることはメンバーに大きな心理的安全性をもたらす。

例えば試作を実施する際に過去の経緯を探すことはよくあることだが、議事録なりが残っているとわかっているのならば探すことは容易である。 議事録は更新する必要のないフロー型のため、とりあえず残しておくという認識であれば問題はない。

また、アプリケーションに不具合があった時に、それが実装のミスなのか、仕様の考慮漏れなのかを判断する際には仕様書が役に立つ。 まずは仕様書を読み、そこに問題がないとき初めてソースコードを読む。 これが仕様書がなければ、いきなりソースコードを読み、何が正解だかわからないが現状どのように動作するかのみ理解できる。 それ以降の対応に関しては仕様を把握している人に聞いて、対応を決定する。 仕様を把握している人がその場にいないことを想像すると寒気がする。

ドキュメント否定派の声

以前は開発の中にドキュメントがあることが当たり前だった環境で働いていた。 職場が変わったことでドキュメントなんて知るかという環境で働くことになった。 そのような中で何度も言われたこととその反論を書き連ねる。

「ドキュメントって必要なんでしょうか」

必要ないと思っているのはあなただけ。 あなたの頭の中には正しい最新情報があるのかもしれないが、他のメンバー、特に新参者はそのような情報は持っていない。 今は逐一聞けば良いのかもしれないがあなたがいなくなったらどうするのか。 退職する場合はあらゆる情報を引き継ぐことも理論的には可能だが、不慮の事故で突然長期不在になったらどうするのか。

加えてドキュメントが書けない人間が作ったシステムが良いシステムになっていないことが多い。 まずは徹底的に文書に落とし込んで穴がないかをチェックしてから実際に手を動かし始めろ。

「誰が管理するのか」

そんなことは本質ではない、誰でもいい。 管理者なんてドキュメント以外でも考えていないものが多いだろう。 管理者が欲しいならPMでもPdMでも立てれば良いし、更新は皆でやっていくものだから気にするな。

「ドキュメントって陳腐化するから」

させるな。 開発フローにドキュメント更新を組み込め。 コードを書く前に現状の確認と更新箇所の確認はするのだから、手を動かす前にエンジニアは頭の中でその整理はやっている。 それをただドキュメントに落とし込むだけで良いのだから、思っているよりは工数を取らない。 エンジニアが更新していないとしたらPMなりPdMなりの管理者が注意すれば良い。

書けていないことを認識する

ドキュメントを書けと言っているものの、事業のフェーズとしてどうしてもそのような時間が取れない、最優先でリリースを一日でも早く行いたい、ということもあるだろう。 そのような場合でも、ドキュメントを書かないとただ安易に決定するのではなく、ドキュメントを書くこと自体は大事であるが、最優先事項があり今は手をつけていない、という認識が必要だと思う。

少なくとも事業が安定してユーザが一定数ついているサービスであれば仕様書を整備するフェーズになっている。 仕様書があることで継続的に安定してリリースをすることができ、それはサービスのファンであるユーザのためである。 仕様書がなくリリースのたびに不具合を起こしているのであれば、それはユーザを裏切ることになっていると自覚しなければならない。

おわりに

最初にも書いた通り、ドキュメントは資産である。 転職直後からドキュメントを書く文化のない中で奮闘し、社内勉強会やテックブログでも言及してきたが、そのような活動の一区切りとしてこのブログにも思いを残した。 現在もなお社内で必要派と不要派がどちらもいるがお互いに相容れない状況になっている気がする。 少なくとも自分の周辺のドキュメント不要派は言語化できておらず理論的に未熟に感じているので、言語化をして議論してきて欲しい。