PHPカンファレンス福岡2023 登壇レポート / 開発者向けブログ・イベント

6月24日（土）に福岡ファッションビルにて開催されたPHPのイベント「PHPカンファレンス福岡2023」にGMOペパボ株式会社小山健一郎（@k1LoW）が登壇しました。セッションでは、小山が開発するtblsというツールを題材に「Documentation as Code」という考え方について解説していきました。

登壇者

小山健一郎　＠k1LoW
GMOペパボ株式会社技術部技術基盤チーム

tblsとは

ドキュメント運用の1つのアプローチであるDocumentation as Code（その一部はhttps://speakerdeck.com/k1low でみることができます）。そして、Documentation as Codeを実現したツールがtblsです。

tblsは、データベースからドキュメントを生成するCIフレンドリなツールであり、データベースに接続してER図付きのマークダウン形式のドキュメントを生成します。2018年5月17日より開発がスタートしており、PostgreSQL、MySQLをはじめとするRDBMSのほか、BigQueryやAmazon DynamoDB、Cloud Spannerなど14のデータソースに対応しています。

Documentation as Codeとは

ドキュメンテーションについてのコミュニティである「Write the Docs」において、Documentation as Codeとは、「コードと同じツールを使ってドキュメンテーションを書くべきだという哲学」と定義されています。小山はこの定義に対し「システム開発の近くにドキュメント作成の仕組みを置くことで、開発サイクルのなかにドキュメント作成を統合して、システムとドキュメントの乖離を少しでも小さくしようという考え方だと思っている」と、自身の解釈について説明します。

ただし、システムとドキュメントの乖離を小さくするという考え方のみでは、実用に耐えない場合もあると小山はいいます。

「たとえば、システムのアーキテクチャを説明しているドキュメントにはAと書いてあったのに、現場の人に聞いたら『それは先週Bになった』といわれてしまうケースが考えられる。こうして開発時にドキュメントとの乖離があると手戻りが発生するおそれがある。すると、誰もドキュメントを信用しなくなり、読まれなくなる。結果として、ドキュメント更新のモチベーションが低下し、システムとドキュメントの乖離がさらに広がるという負のループに陥る。かといって、システムは日々開発が進むため、機能追加や改修の際、常にドキュメントと一緒にPull Requestを出せるかというとそうではない。ドキュメントをレビューするタイミングがないというのも課題になる」（小山）

システムとドキュメントの乖離をゼロにする「Documentation as Code+」

そもそもシステムとドキュメントの乖離はなぜ起こるのでしょうか。小山は、「システムは時間の経過によって変化するが、ドキュメントはその変化に追従しない、もしくは追従するにもタイムラグが発生するため」と説明します。そして、「時間経過に耐えうるには、システムを都度そのままドキュメントに変換できればよい」とします。この結論は、実際に小山がモデル化して導出し、確認したといいます。さらに、システムをそのままドキュメントに変換するには、「システムからドキュメントのもとになる構造化データを抽出できればよい」と指摘する小山。「これにより、システムとドキュメントの乖離をゼロにできると考えた」と述べます。

（参考）「システムの変化に追従可能でかつ理解し易いドキュメントシステムのモデル化」

このように、システムとドキュメントの乖離をゼロにするというアプローチを取るDocumentation as Codeを、本セッションでは便宜上、本来のDocumentation as Codeと区別して「Documentation as Code+」と呼びます。

Documentation as Code+のアプローチは大きく分けて2つあります。1つめは、システムから構造化データを抽出し、その構造化データからドキュメントを生成するというもの。PHPDocやGodocといったソースコードからドキュメントを生成するアプローチがこれに相当します。

2つめは、構造化データからシステムとドキュメントの両方を生成するアプローチです。これは、OpenAPIやProtocol Buffersのprotocなどがそれに相当します。

ドキュメントの活用範囲を広げる「Documentation as Code++」

tblsは、構造化データ（データベース）を抽出してドキュメントを生成するアプローチ、つまりDocumentation as Code+の視点で作成されていると小山は説明します。

tblsでは、データベースとドキュメントのタイムラグをできるだけなくすために、CIで継続的にドキュメントを生成すること=継続的ドキュメンテーションが推奨されています。tblsはワンバイナリで簡単にインストールでき、CIフレンドリであることが特徴です。

（参考）「CIフレンドリなDBドキュメント生成ツールでドキュメントの最新を維持し続ける」

（参考）「Continuous Documentation – CI/CDパイプラインを活用した文書化技術」

ただ、運用していくなかでは、Documentation as Code+にも課題があることがわかってきたとする小山。「tblsによって正しいデータベースドキュメントであるという安心感は得られたが、システムの開発ライフサイクルにおいて役に立つタイミングが少なく、作成して満足している状態になってしまっている」と説明し、その理由と対策の方針について次のように考察しました。

「データベースのドキュメントの情報だけでは足りないのかもしれないと考えた。データベースから抽出した情報以外の情報もあったほうがよい。また、ドキュメントの形式がマッチしていない可能性もある。正しいデータベースドキュメントは正しいデータであるため、データ活用の接点を増やしたほうがよいのではと考えた」（小山）

このようにドキュメントの活用範囲を広げる方針を、便宜上「Documentation as Code++」とします。

ドキュメントにアノテーションを付与する

Documentation as Code++のアプローチとして、まず、情報が足りなければ足していくという考え方について具体的に考えてみます。

小山は、ソフトウェアアーキテクチャの世界にあるビューやビューポイントといった考え方をもとに、ある1つのアーキテクチャをさまざまな切り口で表現することで全体を理解すればよいという考え方を紹介します。

「関心事にあわせてアーキテクチャを1つ以上の側面で表現するという考え方は、設計だけでなくドキュメンテーションにも当てはめることができる。ビューやビューポイントのスコープは、そもそもドキュメントにも入っており、関心事にあわせて必要なシステムの要素だけをまとめてビューとしてドキュメント化してみてはどうかと考えた。実際に、システムアーキテクチャをドキュメントするためのツールを作成するなどして効果を実感している」(小山)

（参考）「目的に沿ったDocumentation as Codeをいかにして実現していくか」

tblsには、スキーマやテーブルのカラムにラベルを付与できるラベルという機能があります。ラベルはそのままドキュメントや構造化データにも反映されます。たとえば、GMOペパボでは、漏洩してはいけない情報に”sensitive”というラベルを付与し、マスクしたり権限を限定したりといった用途で活用しています。

また、最近では、関心事にあわせてテーブルやラベルを絞り込み、その関心事を説明するためのドキュメントを別途作成するviewpointという機能もtblsに追加されました。.tbls.ymlファイルにviewpoointを追記して利用します。小山によると、さらにグルーピングなどによってよりわかりやすくするような機能も作成しているといいます。

中間的な構造化データを活用する

ドキュメントの形式がデータベースにマッチしていないかもしれないという課題に対しては、ドキュメント以外のアプローチを考えていきます。

tblsでは、v1.57.0からtbls docでschema.jsonがデフォルトで出力されるようになっています。schema.jsonは、データベーススキーマと.tbls.ymlを利用してドキュメントを生成するために内部で構築される構造化データです。このアプローチについて小山は「デフォルトでschema.jsonが出力されていれば、それがある前提でさまざまな実装ができるという考えが根底にある」としたうえで、詳細について次のように説明します。

「tblsの内部では、MySQLなどのデータベースの情報をそのまま中間データとしてschema.jsonに落としており、実はschema.jsonはデータソースとして使えるような形になっている。つまり、schema.jsonさえ保存しておけば、実データベースに保存していなくてもドキュメントを再生産することが可能となる。この仕組みを活用したのが、tbls ls。データベースのテーブル一覧やカラム一覧を出力するコマンドで、ドキュメントを見に行かなくても、schema.jsonから内容を見ることができるというもの」（小山）

LLMの活用可能性

小山は、ドキュメントの適用範囲をさらに広げるためにLLM（大規模言語モデル）を使用している事例についても言及しました。

tblsでは、データベースドキュメントが正しいことがわかっており、コメントやビューポイントなどコンテキストを理解するための情報も多く持っています。この特徴に対しLLMの強みを利用すれば、コメント付きの正しいデータベーススキーマと質問をLLMに与えることで、データベーススキーマとコンテキストに沿ったSQLクエリを生成するといったことが可能となります。小山によると、実験的実装としてtbls askというサブコマンドを作成したといいます。tbls askは、schema.jsonから正しいコンテキストを持ったデータベーススキーマを作成し、内部的にプロンプトに仕様するコマンドです。このようにLLMによって正しいドキュメントを使った推測というアプローチが取れるようになります。

また、小山は、逆のアプローチとして、テーブルのレコードのサンプルを与え、LLMにテーブルとカラムの説明を推測させるということも可能であると紹介しました。

おわりに

小山によると、tblsは、Documentation as Codeについて考えながら継続的に開発してきたツールであるといいます。これを踏まえ、次のようにコメントして講演を締めくくりました。

「Documentation as Codeの原点は、ドキュメントとコードを同じように運用していくという考え方。そして現時点においてDocumentation as Codeは、『正しいドキュメントは正しいデータであり、ドキュメントの範疇を超え良質な入力になる』ものだと私は考えている。ぜひこのアプローチでドキュメントをよりよくしていただければ」（小山）