【エンジニアコラム】ドキュメントはできるだけ作るな
エンジニアの仕事はコーディングだけではないです。むしろ設計や既存の製品の仕様をまとめるためにドキュメントを作成する時間が長いです。むしろコーディングの時間よりも長い人もたくさんいらっしゃると思います。
しかしその長い時間をかけてドキュメントを作る作業は意味がないかもしれません。むしろ悪影響を生んでしまいかねないと私は考えています。
なぜそのように考えるのか、またそのような現状にどう対応すればよいのかをお伝えします。
ドキュメントはすぐ負の遺産になる
仕様を記載したドキュメントはすぐに負の遺産になります。仕様が変わればドキュメント修正タスクが発生します。もし修正が漏れればそのドキュメントはむしろ読んだ人に誤解を与える悪いものになってしまいます。これらはドキュメントがそもそもなければ起こりえないことです。
ドキュメントが詳細に書かれていればいるほど修正箇所が多くなりメンテナンスコストがかさみます。ドキュメントがあって嬉しいのは結局作った直近のタイミングのみです。仕様理解は簡単になるかもしれませんが、最新の情報が反映されているのか分からないドキュメントはあてにできません。
以上のことから仕様を記載したドキュメントはできるだけ作るべきではないのです。
どう対応するのか
ドキュメントを作成することによる悪い点は理解いただけたと思います。しかし仕様に関するドキュメントが全く存在しないことも望ましくないです。仕様がドキュメントにまとまっていないので、仕様を知りたければ毎回コードを読む必要が生まれてしまうためです。それでは業務効率が著しく下がります。
私がお勧めするのは最新のコードを基にしてドキュメントを自動で生成することです。コードはGitなどのツールを利用してバージョン管理されている会社がほとんどであるため、コード自体はどれが最新かすぐに判断がつきます。
この最新であることが簡単に判断がつくコードからドキュメントを自動生成することが出来れば良いのです。
一例としてPythonにはFastAPIというWebアプリケーションフレームワークがあります。このフレームワークを利用してAPIを作り、APIサーバーを起動させると特定のURLにアクセスしたときにAPIの仕様をWeb上で表示させてくれます。この機能を利用することでAPI仕様についてまとめたドキュメントを作成するタスクは消滅します。
このような形で最新であることを簡単に担保できるコードを利用してドキュメントを生成することが最良の方法だと思っています。タスクはできるだけ少ない方が良いです。またドキュメントは常にコードの最新の状態が反映されているべきです。FastAPIのような仕様を自動で生成してくれる機能はこのどちらも満たしてくれます。
ただこのやり方には制限があります。利用しているフレームワークによってドキュメントを自動生成できないかもしれません。また必要なドキュメントをコードから自動生成してくれるソフトウェアもまだないかもしれません。
そんな時、次におすすめなのがコードのコメントで仕様を残すことです。APIのコントローラーの個所にインプットアウトプットの仕様を書き、それらのファイルに仕様が書かれていることをREADME.mdに書いておく、こうすることでコードを読むことなくコメントを拾うだけで最新の仕様を把握できます。
いずれの手法でも共通しているのが、最新であることを担保しやすいコードと仕様ドキュメントを紐づけることです。これが出来れば更新が漏れた悪いドキュメントを発生させない確率がグンと上がります。
作成してよいドキュメント
私が作成してよいと思うドキュメントは「メンテナンスが不要」なドキュメントです。
人の手によるメンテナンスが必要なドキュメントは管理する人が変わったタイミングや忙しくなったタイミングで確実にメンテナンスされなくなります。メンテナンスされなくなったドキュメントは無駄です。
逆にメンテナンスが不要な実装前の設計などのドキュメントは作成すべきだと思います。箇条書きなどで処理が分かりやすく記載された設計ドキュメントを作ることでレビューが容易になります。コードのレビューは仕様のレビューだけではなく、変数名やライブラリの選定、改行有無、関数分割など確認するべき個所が大量にあり、負担が大きいですが、設計ドキュメントがあることで目的を分けたレビューが可能になります。そして質の高いアウトプットにつながります。
まとめ
最近業務で別のチームが作成しているソフトウェアの仕様を確認するために、社内Wikiで仕様を確認していたところ、社内の重鎮の方から「そのドキュメントは更新されてるか怪しいから直接ソフトを動かして確認した方が良いよ」と言われたことから今回の記事を書いています。
何社か経験していますが、このような状況に陥っているプロジェクトがほとんどでした。IT業界はどこも人が足りておらず、優先度が低くなりがちなドキュメント更新タスクは忘れさられることが多いです。
エンジニアは怠惰であるべきですが必要な業務を怠けてはいけません。必要な業務を可能な限り効率的かつ質高く行うのが真の怠惰なエンジニアです。
コードからドキュメントを自動生成してくれるツールを探してみてください。どんな言語でも何かしら見つかると思います。
真に怠惰なエンジニアを目指しましょう。
