目的に沿ったDocumentation as Codeをいかにして実現していくか by 小山健一郎

あるシステムを理解して開発を開始するとき、必要なのはInfrastructure as Codeを含むソースコードだけでは大抵の場合は不十分です。では挙動がわかるようなテストコードがあれば十分かというとそうでもありません。
いわゆる「オンボーディングの効果的な運用」「開発開始までのオーバヘッドの削減（PHPerKaigi2020で発表）」は継続的な生産性向上のためには考えなければならない要素です。
そして、上記を補完するためにしばしばドキュメントが書かれます。

私はドキュメント運用のアプローチとして「コードによる生成を含んだドキュメント運用」に興味を持っています。
私はこれを「Documentation as Code」と呼んでいます。そして、そのような概念はすでに世の中にあり、時として「Documentation as Code」と呼ばれているようです。
例えばPHPDocなどはソースコード自体の構造とアノテーションをトレースしてドキュメントの自動生成を実現しています。
OpenAPIのように構造化されたデータとして情報を記述することでドキュメントと同時にAPIクライアントやの自動生成が実現できている例もあります。 これらはコードによってドキュメントが管理されており、継続的なドキュメンテーションも実現可能です。
さて、ドキュメントと言っても「何を解決するためのドキュメント」なのかを考える必要があると思います。
本発表では、上記のような「Documentation as Code」を実現するツールを独自にモデル化してそれぞれの特性について考えます。
そして、どのような「Documentation as Code」が「開発開始までのオーバヘッドの削減」に繋がるのか、私が実際に取り組んだ（また取り組んでいる）事例を交えて考えていきたいと思います。