最初に
皆さんはドキュメントとどのように付き合っていますか？
前職はベンチャー企業ではあったのですが、割とウォーターフォールに近く、決められた仕様を満たしていればOKというふうな感じだったので、
仕様書を書いて、エンジニア数人で仕様書レビューをして、OKが出たら実装して、テスト前にテスト仕様書書いてテスト仕様書のレビューして。。。というふうに開発を行っていました。
今はスクラムマスターがいる環境でアジャイルで開発を行っています。
ドキュメントに関しては特に決まりはなく、開発者が書いたほうがいいなと思ったタイミングで書かれています。
ドキュメントは必要だという話は良く聞くし、ただ毎回しっかりドキュメント書くのも結構大変だよな。。。
というふうに思っていて自分の中でいい落とし所があればいいなと思っていたのですが、
最近一旦その落とし所を見つけた気がしたのでこの記事を書いています！
（アジャイルの文脈が強く、がちがちなウォーターフォールプロジェクトとは相性が悪いと思いますのでご注意を。。。）
自分が考えた方針
本当に必要になったタイミングでドキュメントを作る。
効果的なドキュメントしか作らない。
説明
本当に必要になったタイミングでドキュメントを作る。
→ 文字通りなのですが、重要で差し迫った必要のあるドキュメント以外はつくらないということです。
効果的なドキュメントしか作らない
→ 【効果的な】の部分は明確に定義はできないのですが、参照される回数が多く、作業時間や調査時間などを削減する効果が大きいものをここでは【効果的な】としています。
自分はなぜドキュメントを網羅的に書くべきではないと考えているか
→ 理由は3つあります。
１つ目はドキュメントに時間をかけるよりも、できる限り早くコードを動くようにして、実際にシステムを使う人に使ってもらってフィードバックをもらうことを最優先すべきだと思っているからです。
開発前にどういう処理を書けばいいのか、考慮点などは考えておくのですが、実際コードを書いてみると「この処理も必要だった」「この考慮しなくちゃだったな〜」っていうことがどんどん出てくるんです。
そしていざ形にして、使ってもらうと今度は「もっとこうしたほうがいいね」「運用的にこういう使い方もするんだよね。。。」などなど要望や改善点、フィードバックが出てくるんですよね。
ここで何を伝えたいかというと、
自分で手を動かしてみて、相手にシステムを使ってもらってみて初めて気づくこと、わかることがあり、
最初からすべてを予測しきるのは現実的に難しい
ということです。
であれば最初から予測しきる努力をするんじゃなくて、早く使ってもらうところまでいく努力をしたほうが効果的なのではと思っています。
２つ目はドキュメントの整合性を保つことが難しいからです。
網羅的にドキュメントをかけば書くほど、ドキュメントを修正する必要性が増えてしまいます。
（仕様の変更などで挙動が変わった場合などに。そして開発の文脈だとそれらは頻繁に起こる）
それはつまり、【ドキュメントが正しくない】可能性が出てきてしまうということです。
ソフトウェアを作っているのは人間なので、コードはなおしたけどドキュメントはなおし忘れていた。。。
ということはざらに起こります。
そうなると最後には「本当に正しいのはソースコードだから直接ソースコードを見に行ったほうが早いし正確だ」という状況になってしまい、読まれないドキュメントになってしまうと思っています。
メンテナンスされていないドキュメントが存在していると、そこには嘘が書かれていることになり、逆に混乱を招く可能性もあります。。。
3つ目は網羅的にドキュメントを書いても、殆どのドキュメントは再度見返す機会自体あまりないのでは？と考えているからです。
信頼できるのはドキュメントよりソースコードです。
例えばバグが起こったときはコードを見に行きますし、
何か機能の調査でも該当機能のコードを見に行くのが確実で最短です。
ですので網羅的にドキュメントを書いても、基本的には殆どの場面で再度読まれることはあんまりないんじゃないかなと思っています。
（複雑すぎてコードを読んでもよくわからない機能や難しいアルゴリズムを実装している機能などについてはドキュメントがあったほうがありがたいので、そういう場面でドキュメントを書くのは良いと思っています。
【本当に必要になったタイミングでドキュメントを作る。】に該当します。）
ドキュメントに極力依存しなくても良くなるように意識すること
Whyの部分はソースコードのコメントに書き込む
→ 実際のコードに近い部分でWhyが書かれていると、ドキュメントで表現するよりも効果的になります。
（コードを読みながら咀嚼できる）
コードはできる限りシンプルに保っておく（仕様はシンプルに保っておく）
→ コードをすんなり読める状態に保っておくと、ドキュメントの必要性が相対的に下がっていくのではと思っています。
命名には特に意識しておく
→ これも上記と同じです。
QA
もし引き継ぎをしなければいけなくなったらどうするのか？
→ 引き継ぎが必要になってドキュメントも必要になったそのタイミングが、一番効果的にドキュメントを書くタイミングかと思います。
そのときに用意するのが良いかと思います。
新人教育はどうするか？
→ 新人が少数人であれば一緒にペアプロをしたり、1 on 1をしたり、質問しやすい環境を作ります。
一見、対面でのコミュニケーションは非効率的だと思うかもしれませんが、
対面でのコミュニケーションは新人くんがチームに溶け込んでいく一つのきっかけになります。
チームに溶け込んでくれて、新人くんが質問できるような心理的安全性を確保することができれば、新人くんはより早く成長することができます。
それと対面コミュニケーションのほうが伝えたいことをより詳細に、ついでに周辺のことも同時に伝えることができるので良いかと思っています。
もし、新人が数十人とか入ってきて、一人ひとりに時間をさくことが難しいということであれば、新人が数十人入ってくるとわかったタイミングがドキュメントを整えるタイミングなのではと思っています。
新メンバーに仕事内容を伝える時にもっとも役に立つドキュメントは「コード」と「チーム」そのもの。
契約の中の納品物にドキュメントがある場合はどうするか？
→ それは最初からドキュメントが必要になってしまったので、最初からきっちり仕様書なり設計書なりを残しておく必要があります。
最後に
今回の記事は自分の経験則であったり、自分の肌感の話が多いので、参考にならないことも多いと思いますが、
ドキュメント疲れを起こしている人、自分のプロジェクトでドキュメント書いてるけどあんまり意味を感じられてないんだよな〜って人に対して、ドキュメントの方針を考え直すきっかけにでもなれば幸いです。
ドキュメントの方針や運用で、こんな感じでやってるけど上手くいってるよ！っていう人いたら、教えて下さい！
よろしくおねがいします🙇♂️