はじめに
最近、仕事・プライベート問わず技術的な内容に関して人に教える機会をいただくようになりました。
僕は前のチームの影響で文章を書くことの重要性を意識するようになりましたが、最近はどうしても面倒で後回しにしがちなドキュメントをどうやったら書けるようになるかということについても考えています。
なぜドキュメントは大切なのか
ドキュメントの重要性は、個人的な感覚ではテストコードに近いと思っています。
特にプロジェクト初期や設計の段階では、「なぜその技術を選んだのか」や、「なぜこの方針にしたのか」といったことを議論したり、複数の選択肢から技術を選定するためにさまざまな比較検討を行います。
このとき、決めたことはコードとして残りますが、「検討したが採用しなかったアイデア」についてはコード内ではなかったものにされ、見えなくなってしまいます。正確に言うと、コードとしては不要なものはいらないのでそれは正しいですが、そのシステムを運用していくと時代の流れとともに「技術選定の記録」は忘れ去られてしまいます。また、年数が経つので技術のトレンドや、あるスタックが持つ機能などにも変化が生まれ、「当時は選択できなかった筋が悪い方法」が劇的に改善されることもありえます。
こうした流れの中で、運用者ないしは開発者の中で疑問が生まれることがあります「そう言えばなんでこの実装ってこんなに筋が悪いんだっけ？」と。
デザインパターンなどを採用すると、保守性や再利用性の高い、息の長いシステムを作ることができます。しかし、時として機能実装を優先するために敢えて筋の悪い方法を取らざるを得ないことは往々にしてありえます。これは実装者のスキル不足はもちろんですが、採用しているライブラリやフレームワークの実装上の制限により実現できないものをあえて自作したり、インフラだと手作業を挟むようなシーンが該当します。
このような制限事項は放っておくとそれだけで技術的な負債になります。人類はGitHubにIssueをたてたり、余裕があればPull Requestを送るなどして将来的な解決を図りますが、中には場合取り込まれるまでに時間がかかったり、OSSのオーナーの意図に沿っていないなどの理由で見送られてしまうような要望もあるかと思います。
いずれにせよ、検討したがダメだったという事実は残しておかないと、忘れた頃に自分でまた検証をするか、その事実に気づいた他の人の検証コストを割くことになります。
なぜドキュメントは面倒なのか
ドキュメントは基本的に書くのが面倒です。そもそも、人類は言語化に頭を使います。実装のイメージを図やロジックで表現していたものを、ドメイン知識と組み合わせて説明するための資料を作るというのは、本質的に大きなコストを要求します。
今書いてるコレも一気にたくさん考えて書いてるのでめんどい。
めんどくさくないドキュメントの書き方
インフラでもアプリケーション開発でも設計構築するときには必ず検証をおこないます。やってない人はやってください。
検証したときのメモをちゃんと残す。たったそれだけでドキュメントは一気に書きやすくなります。書き溜めすぎない。チケットごと、Issueごと、タスクごと、機能ごと、なんでもいいですがそれごとにちゃんと何をどうしたか書き残しておく。それだけじゃないなと思います。
いいドキュメントとよくないドキュメントの違い
- だらだら長ったらしくなく、結論と主述関係がわかりやすい日本語で書かれている
- 文字で表しきれない情報を図や表を使って書かれている
- 考察や仕様の根拠が分かる(e.g. Refのリンクがあったり、実証結果が書かれていたり)
- 上手くいった方法だけではなく、他に検討した方法やそれぞれの問題点・課題などについて書かれている
他にもありそうだけど今日はこのへんで
