開発者こそドキュメントを書くべき

開発者こそ自らの手でドキュメントを書くべきだ、というのが Contact Form 7 の開発を20年間続けてきて僕がたどりついた結論です。

ドキュメントを書くという行為を通じてあなたは誰かにプロダクトや機能の説明をすることになり、理解してもらうための工夫に頭を働かせることになります。その過程で自然と、漠然としていたアイデアが整理されていき、そしてアイデアが整理されて初めて、そのプロダクトや機能の最適な設計が見えてきます。どのようなクラスやインターフェイスを導入すれば設計を無理なく落とし込めるか、変数ひとつとってもどのような名前をつけるのが整合的か、そういった細かな判断もアイデアが整理されて初めて可能になります。

僕はまずドキュメントを英語で書きます。読者の大多数が英語を理解するからという理由もありますが、母語ではない言語を使うことで物事を客観的に捉えることができるからというのがより重要な理由です。日本語で説明しようとすると深く考えていなくてもペラペラと上手に言葉をつなげてなんとなく説明できたような気分になってしまいますが、実際には何も説明できていない、という事態によく陥ります。母語ではない言語で苦労して慎重に文章を構築する行為を習慣化することでそのような落とし穴を避けることができます。

自分で思っているほどには開発者は自分で作っているプロダクトについて理解していないのではないでしょうか。ドキュメントを書く行為に向き合って、自分の理解の浅さを思い知る、という経験が僕自身のキャリアの中で何度もありました。ドキュメントなんて AI に書かせたらいいじゃないか、という声もあろうとは思いますが、僕はむしろ、ドキュメントを書くという人間にとって極めて有益な機会を AI に譲渡してしまうなんて馬鹿げていると思っています。昨今の生成 AI 技術の優れた面は認めつつも、それを実際に使うかどうかはそれが自分自身にどういう影響を及ぼすかも考慮に入れて判断されるべきです。