レギュラートーク(20分)

Documentation as Codeとは何か PHPerKaigi 2021

6
k1LoW 小山健一郎 k1LoW

私はドキュメント運用のアプローチとして「コードによる生成を含んだドキュメント運用」に興味を持っています。
私はこれを「Documentation as Code」と呼んでいます。そして、そのような概念はすでに世の中にあり、時として「Documentation as Code」と呼ばれているようです。
例えばPHPDocなどはソースコード自体の構造とアノテーションをトレースしてドキュメントの自動生成を実現しています。
OpenAPIのように構造化されたデータとして情報を記述することでドキュメントと同時にAPIクライアントやの自動生成が実現できている例もあります。
テストケースに振る舞いを自然言語で併記しながらテストコードを書くことで結果としてテスト仕様や要求仕様のドキュメントで実現するようなアプローチもあります。
私もシステムやコードからドキュメントを生成するようなツールを少なからず作ってきました。
そういった経験から、本発表では、上記のような「Documentation as Code」を実現するツールを独自にモデル化してそれぞれの特性について考えていきます。
そして本発表を通じて皆さんが「Documentation as Code」に興味を持ってもらえればと嬉しいです。