2023/12/6、Findyさん主催のドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT に「設計ドキュメント腐る問題、Git管理で運用してみた本当のところ」というタイトルで登壇しました。
ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT 会とは
ドキュメントの管理方法を確立、整備されてこられた方々にお話を伺い、工夫点や考え方、テクニック等を広く共有していただくことで、明日から使える技術やノウハウを共有することを目的にした勉強会です。
Lunch LTということで、お昼時に4名で10分枠、質疑応答で15分ごとに交代でした。私の家族構成的に夕方以降の勉強会参加が厳しいので、ランチLTだと視聴だけではなく登壇もできるということで、控えめに言って画期的だなと思いました。
登壇
トップバッターで「設計ドキュメント腐る問題、Git管理で運用してみた本当のところ」というタイトルで登壇しました。登壇のきっかけが、設計ドキュメント腐る問題、Git管理で運用してみた結果という記事を見たFindyさんが声をかけてくれたことですので、記事を見ていない人向けに、記事のエッセンスや書きそびれてことを話しました。
このスライドも微妙にふわっとした内容で人によって捉え方も様々であり、ツッコミしやすいためか、SNSなどでたくさんコメントを頂いています。糧としたいと思います。
久々の勉強会の登壇で楽しかったです。他の登壇者の方の考えも聞けてよかったです。重複する部分もあれば、先に進んでいる施策を取っているところもあり、私の勉強になりました。
質疑応答や反応
勉強会で頂いた質問についてです。
- 最初にドキュメントをGit管理へ移す際に、苦労された点はありますか？
- (回答) スライドやスプレッドシートをファイルサーバ（Google Drive)に保存する方式でしたので、それらへの記載内容をテキストベースで記載できるか、実現性を示すことが大変でした。特に、表形式の情報はどう頑張ってもExcelに記載するほうが楽なので、Markdownでも書けるとか、Diffで差分が管理できるなどをチームに説明した記憶があります
当日にもう1点、質問に答えたのですが、内容を忘れちゃいました。
Web上で上手く探せなかったのですが、発表を聞いてくれた人のコメントで、「ドキュメントを後で揃えるのは、テストコードを後から書こうとするのに似ている」というのがあって、「確かに！」と思いました。最初にどういった構成、粒度、レベル感で記載するかを定義し、リファレンス実装（ドキュメント）を用意することが重要な点も似ていますね。
設計ドキュメント、主題はアーキテクチャ方針をどこで管理するか話だったかもしれない
設計ドキュメントの管理ですが、「コードと設計ドキュメントを同時に更新する開発ルールにすればおしまいだよね、それで話が終わりじゃない？」みたいなリアクションがあり、一定その通りだと思います。おそらくプログラム設計書とか、アーキテクチャ図、システム間連携I/F仕様書、DBのテーブル設計書あたりは機械的にそのルールで行ける気がします。静的解析やコード自動生成でCI的なワークフローにも組み込みしやすそうです。
逆に、システムの構成が変わるようなものの、検討経緯はそのパターンで扱いきれないときがあります。アーキテクチャ方針とかそういったものです。
いくつか例をあげます。
- ある処理は非同期に切り出そう
- あるファイルアップロードはいったんS3に格納して受付OKをクライアントに戻し、取り込み要求をキューイングして、非同期で処理する。なぜそうしたか？ 同期で全て取り込むAPIもあり、2種類あるのはなぜで、使い分けはどう考えるべきのか
- 出荷指示、在庫引当などモノが動く以上、トランザクション観点で同期で処理すべきだが、非同期になっている。なぜか。もし、実在庫とシステムでズレが出た時のデータ不整合はどう救済するのか
- DBのテーブルが命名体系があり多段になっている。データレイク層・正規化層・データマート層といったレイヤー分けがある。なぜそうなったのか。どのような使い分けか？
最初に全てアーキテクチャ的な方針が決まっていれば良いですが、設計開発～保守運用など様々な場面で、方針を進化させる時期が出てきます。それらをコード（というより暗黙的なチームの合意事項）と同期を取るために、開発ルールを決めれば、ちゃんと書いてくれるでしょうか？ もし開発ルールを決めて自発的・自律的にアーキテクチャレベルのドキュメントを同期とってくれるチームであればかなりハッピーだと思います。良いチームですね。そういったチーム文化を作るためには通常は工夫が必要です。最初にPull requestで設計レビューを挟む（やりすぎると重厚ですが、チームメンバーの規模・スキルセットによっては厳密化する）方式でレールに乗せるまではレビューで担保するとか、色々です。
勉強会では、それらアーキテクチャデザインレコード的な内容は、イミュータブルドキュメントモデルとして切り出して管理したり、あるいはドキュメントサイトをVitePress（Vue.jsを利用した静的サイトジェネレータ）で構築したり記載する障壁を下げる工夫をしたり、各社の知見が大集合で話されていました。
勉強会名は今思うと、「アーキテクチャ方針を陳腐化させないための実践事例 Lunch LT」というのにすれば、ブレが少なかったかもなと感じます。
設計ドキュメントはブログ運営に似ている
アーキテクチャ方針など、決定事項の経緯や議論内容を上手く記載するにはそれなりの訓練が必要です。ブログをよく書くメンバーは筆が軽く、そうじゃないメンバーは腰が重いことがあると、発表でも伝えました。
個人的にサイト化すると、TOCを自動生成の他にも、そのページのPVや、記事に対するコメント、いいねなどのリアクションを遅れるようになると感じました。また、その記事に対する、被リンク記事を収集したり、関連性の高い記事をサジェストするなどです。人気の記事ランキング、みたいなのを出しても良いかも知れません。良い記事に多くコントリビュートした人を礼賛する、ドキュメントライター賞みたいなのを作っても良いかも知れませんね。
ドキュメントの質を上げるため、メンバーのモチベーションを上げる取り組みがあに越したことはないでしょう。この面はブログ運営のナレッジが役立つと思います。また、こうした設計ドキュメントを書く文化を整えれば、メンバーが自社の技術ブログを執筆する際の心理的障壁も取り除け、スキルセットもシームレスになります。
社内ドキュメントを書いていけば、技術ブログ執筆スキルが上がるし、逆もまたしかり。相互に影響しながら進化させれるなと気づけたので、勉強会に参加して良かったです。
最後に
Findyさんの抜群の集客力で400名以上の方が参加申し込みしてくれ、またLunch LTという私にとって登壇しやすい時間帯・形式で勉強会に参加でき、とても嬉しかったです。
また、今後はドキュメント周りについてはプログラム設計の話をしているのか、アーキテクチャ設計の話をしているかで取り扱いノウハウが異なりそうなので、解像度を上げていきます。