第8回Web System Architecture研究会に参加して「システムの変化に追従可能でかつ理解し易いドキュメントシステムのモデル化」について発表した #wsa研

wsa.connpass.com

オンライン開催に参加してきました。

予稿

github.com

発表資料

システムの変化に追従可能でかつ理解し易いドキュメントシステム

発表内容はドキュメントシステム(ドキュメンテーションツール)についてです。

私は、システムを理解するためにかかる時間(いわゆる「オンボーディングまでのコスト」。私は「開発開始までのオーバーヘッド」と呼んでいます)をいかに継続的に削減できるかに興味をもっています。

それはなぜかというと「私がシステムの理解のセンスがないからそれをなんとか技術で解決したい」という個人的欲求に他ならないのですが、「まあオンボーディングのコストが小さくなればそれはエンジニア全員にも良いことだろうな」と勝手に思い込んでいろいろ作ったりしています。

実は今回の発表にいたるまでには過程があって、July Tech Festa 2021 winter ではDocumentation as Codeというキーワードで継続的なドキュメント運用の実現方法について主張しPHPerKaigi 2021ではその主張をさらに進めて発表しました

www.youtube.com

そして今回のWSA研では、集合を使って「継続的なドキュメント運用」「理解しやすいドキュメント」についてモデル化し、有効性を主張してみました。まだまだ前提などが甘々ですが、やはりWSA研、有用なフィードバックを多くいただきました。ありがとうございました。

実装としてのndiag

さて、上記の発表の主張に沿って実装しているのが ndiag です。

github.com

嘘です。

実際には逆で、いかに継続的にドキュメントを運用できるかウンウン考えて試行錯誤しながらndiagを開発し、その設計思想を整理したのが上記の発表です。

ndiagがどのようなドキュメンテーションツールなのか?については割愛します。公式チュートリアルや、実際に使ってみたエントリを書いてくださっている方もいらっしゃるので(本当にありがとうございます!!)そちらをご覧ください。

zenn.dev

「システムが頻繁に更新されるならシステム自体を観測してそこからドキュメントを作成すればいい」というアイデアは、真新しいものではありません(PHPerKaigi 2021の資料にその例が掲載されていて、わかりやすいと思います)。私自身も tbls という自身で作成したデータベースドキュメンテーションツールの開発で効果を実感しています。

github.com

ndiagで実現したいと思っていることは、まだまだ全ては実装できていません。それは、主に私の技術力や、開発に確保できる時間、ついつい発散してしまうモチベーションなどが原因です。

ただ、システムの継続的なドキュメンテーションを実現するのに有用そうな技術もどんどん生まれてきているので、もう1、2歩進めることができるんじゃないかなあと思っています。

とりあえず今の主張は以下です。

まとめ

今回もWSA研は楽しかったです。いつも受け入れていただいてありがたいです。

特に @YutaroHayakawaさん の発表と、懇親会でのいろいろなお話が「頑張らないとな」と思うことが多々あり「頑張らないとな」という気持ちです。

みなさんお疲れ様でした!!