はじめに
技術の進歩は早く、少し前に「あんなことできたらいいなぁ」と思っていたことが、結構身近に感じることも多くなりました。
ドキュメントの自動生成もその一つです。
ですが「できるようになった」=「やるべき」とは限りません。仮に誰も（AI含め）読まないドキュメントを生成しても、意味がないでしょう。
この記事では（体系的ではなくメモ書き程度ですが）飛びつく前に個人的にこの辺は考えておきたいなと思っている点を書きます。
先に簡単にまとめますと、ドキュメントを自動生成する前に、そのドキュメントの「目的（具体的な利用シーンを含む）」と「メンテナンス方法」を定義すべきだと私は考えています。
各ドキュメントの性質の違いを押さえる
一口にドキュメントといっても、本当に様々なものがあります。提案書、設計書、仕様書、手順書などなど。
名前をつけてラベリングすることはとても便利ではありますが、反面、記号的な意味しか持たず、何を指すのかがぼやけることもあります。
よく「そのドキュメントの目的は何か？」のように考えるタイミングはあると思いますが、目的（や性質）を以下のように分解して考えてみたいところです。
- 誰が、なぜ、いつ、読むか
- 誰が、なぜ、いつ、書くか
- 誰が、なぜ、いつ、メンテナンスするか
- 意図を示すものか、実装（設定）を示すものか
もっとシステマチックに 5W1H と「書く・読む・メンテナンス」を組み合わせてもいいかもしれませんが、この段階ではHow（どのように）はやや優先度が低そうです。
以下、設計書とパラメーターシートに絞って少し掘り下げてみます。
設計書
単に「設計書を書いて」と言われたら、どんなものをイメージすればよいでしょうか。
「このフォーマット参考にして」と渡してもらったとしても、目的や利用シーンをおさえておかないと、意味のないものを書いてしまったり、カスタマイズするときに明後日の方向に行ってしまったりすることもあり得ます。
私は多くの場合「設計書」と言われたら、まずいったん、設計の方針のようなものを書くものだと捉えます。たとえば、コーディング規約、命名規則、処理の分割方針などです。
先ほどのポイントを押さえながら目的を表現すると以下の通りです。
- 新規開発時に、開発者が迷わず実装できるようにするために書く
- 機能追加や修正時に、開発者が読み、迷わず追加や修正できるようにするために書く
- あとからプロジェクトに参入した人が実装を追うための手がかりにするために書く
- 方針変更や追加があったら開発者、設計者がメンテナンスする
- 逆に、ちょっとしたコード修正時はドキュメント修正は発生しない
- 実装よりも意図を示すもの
「実装を追うための手がかり」のレベル感が肝で、例えば「あれ系の処理ならこのディレクトリにあるはずだな。どれどれ・・」を促す程度が分かるイメージです。抽象度が高めで、実装との乖離も発生しにくいタイプです。
仮に「そのドキュメントを見れば完全に処理が分かる」ようなものが期待されていると、実装からドキュメント生成という方向が向いていそうです。それができない場合は、実装との乖離が発生しないようなプロセスを整備したり、実装のどの時点のドキュメントなのかを管理する必要があります。
私が思う設計書は、方針の取り決め的なものなのであり、基本的には実装からドキュメント生成という方向はないです。
ただし「今の実装と今のドキュメントを照らし合わせて、ドキュメントに反映したほうがいいものを提案して」と生成AIに依頼するのはありかもしれません。
パラメーターシート
「パラメーターシート」と言われたらどうでしょうか。ここでは、サーバーやプロダクトの設定を事細かに書いたものという前提を置きます。
事細かに書くので、なかなか労力がかかります。目的もなく作成すると、徒労に終わってしまうかもしれないためなかなか注意が必要です。
目的を表現すると以下の通りです。
- 利用者が設定を確認するために書く
- ドキュメント上でしか設定を確認できない場合など
- 設定が変更、追加されたらメンテナンスする
- 意図よりも設定を示すもの
前述の私が思う設計書とは違い、方針というより実装（または設定）を示すドキュメントなので、実装（設定）から自動生成したくなる気持ちが強くなる類のドキュメントかなと思います。
IaC的に管理していて、もしそれだけで事が済む場合はであればドキュメントを人が作る必要はないでしょう。ただし、生成AIによって作成コストが極端に落ちて「事が済む」の判定基準がガラッと変わる場合は、この限りではありません。
とはいえ、冒頭にも書きましたが、誰も（AI含め）読まないドキュメントを生成しても、意味がないどころか、場合によっては混乱のもとになってしまうこともあるかもしれません。
一度自動生成したらおわり？メンテナンスする？
仮にドキュメントを自動生成したとして、そのドキュメントは継続的なメンテナンスが必要なものでしょうか？
どうメンテナンスするか、しないのか、も見越して考えないと破綻してしまいます。
ケース1: 一度生成して終わり
一度生成すれば良くて、実装や要件が変わってもメンテナンスする必要がなく、正しく有益な情報を与える状態を維持し続けられるケースです。
実際のところ、あまり多いケースではないような気もします。
ケース2: メンテナンス含めて自動生成する必要がある
自動生成のたびにドキュメントのフォーマットや章立てがころころ変わったりすると、人間が読むのに負荷がかかってしまいます。その辺を含めてうまく仕組み化する必要があります。
ネットワーク図のようにビジュアル要素が強いドキュメントは特に難しそうです。
ケース3: 一度修正したあとは手動でメンテナンス
メンテナンスは必要だけど自動生成し続けられないケースです。もしかしたら結構あるケースかもしれません。
自動生成したときの楽しいノリに任せて、手動でメンテナンスしにくいものを生成してしまうと、次第に当てにならないドキュメントなり、機能しなくなってしまう可能性があります。自動生成し続けられない場合は、手動でのメンテナンスを見越したボリューム、粒度にする必要があるでしょう。
まとめ
ドキュメントの話は対象分野や風習、価値観などによって呼び方や内容が大きく変わります。
なので、この記事内容で汎用的な考え方を定義できたとは思っていませんが、少なくともドキュメントの「目的」と「メンテナンス方法」は定義する必要はあるだろうなと思っています。
