生成AI時代のドキュメント基盤

生成AI時代のドキュメント基盤

生成AI、活用されていますか？

仕様駆動開発にも注目 AWS - Kiro GitHub - Spec Kit Fission-AI - OpenSpec gotalab - cc-sdd

ドキュメントの重要性 生成AIの活用が進み、ドキュメントの重要性の再認識

ドキュメントの2つの課題 ドキュメント体系 ドキュメント基盤

ドキュメント体系 ソフトウェア開発プロセスの中で いつ 何を文章化し どのように構造化し どうコードとコラボレートするか？

ドキュメント基盤 どう作成・レビューし どう版管理するか？ どう閲覧し どう配布するか？

つの視点 2 ドキュメント体系 : どう構成し、どのように役割分担するか ドキュメント基盤 : どのように作成・レビューし、どう閲覧し、どう配布するか 後者が本発表のスコープです。

年間の蓄積の成果 7

年？GPT3.5でも3年半前では？ 7

時間かけて書いたWordが崩壊してキレた 6

本ドキュメント体系の発端 年前、MS Officeから脱却を決意 WordやExcelで「きれいに書く」ことが負担 複数人による並列作業とレビューの難しさ コードと文書のバージョン同期の難しさ 7

時間かけて書いたWordが崩壊してキレた 6

Markdown ベース文書への移行を決意

結果的に生成AI時代の先取りとなった

本ドキュメント基盤の実績 大手金融3社のSIプロジェクト Markdownベース 800ページ超 最長7年の持続性 これらの事例とノウハウを紹介します。

ハンズオンもやります ユーザーコミュニティイベントで開催予定 4月：C# Tokyo（オンライン） 5月：.NETラボ（東京某所でオフライン）

本題の前に・・・一つだけ

ドキュメントの要否はプロジェクト次第

二つを分けて考える ドキュメントが必要か？ ドキュメントを維持可能か？

ドキュメントとコードの役割は別 ドキュメントは契約 コードは現状

請負開発界隈にとって ドキュメントとコードの 一致：契約履行の証 不一致：契約不履行の証 契約は 身を縛る枷であり 身を守る盾である

コードがあるからドキュメント不要なんてナンセンス

コードは無関係、契約の証跡が不要なら不要

ドキュメント要否は環境次第 自社プロダクトなら不要なことが多い 請負開発なら基本必要

ドキュメント要否の議論は不毛

ドキュメントが維持できないなんて嘘っぱち

コードにバグが入らない程度に文書は維持可能

誤りのある文書が無価値なら、バグのあるコードも無価値？

お金とプロセスがあれば可能

そして生成AIでコストはゼロ（誇張あり）

「できる・できない」ではなく「必要かどうか」

自己紹介 中村 充志 リコージャパン株式会社所属 プリンシパルITアーキテクト Microsoft MVP for Development Technologies 2017/01 （ 〜） 最近、油そばにハマり中 山浦哲朗 リコージャパン株式会社所属 SE歴5年 先週、マーモット村に初めて行っ た。楽しかった。

ドキュメント基盤要件 人間 & AIフレンドリー ブラウザー閲覧 単一PDF出力 単純な図の簡便な作成 複雑な図を正確に描画 表の簡便な作成 管理 PRベースレビュー PR時のステージング git CI/CD 検索を含めた高い閲覧性 高い拡張性 十分なセキュリティ 低コスト 保守ステージのコスト0

DEMO

技術的詳細

静的サイトジェネレーターの選択 実装技術は？ SPAか？静的サイトか？ サイトPDF化をサポートするか？ PDF化時にMermaidやSVGが正確に描画されるか？ 適切なテーマが選択可能か？ Others

代表的な静的サイトジェネレーター プロダクト 実装技術 サイトPDF MkDocs (Material) Python 静的HTML ◎ プラグイン充実 Docusaurus React (TypeScript) SPA △ 外部ツール VitePress Vue.js + Vite SPA △ 外部ツール Sphinx Python (rST / MyST) 静的HTML ◎ 標準機能 Hugo Go 静的HTML ✕ 実質なし Astro (Starlight) Astro (Island Architecture) 静的HTML △ 外部ツール mdBook Rust 静的HTML ○ プラグインあり SPA / 静的

実装技術は？ プロダクト 実装技術 MkDocs (Material) Python Docusaurus React (TypeScript) VitePress Vue.js + Vite Sphinx Python (rST / MyST) Hugo Go Astro (Starlight) Astro (Island Architecture) mdBook Rust

か？静的サイトか？ SPA プロダクト SPA / 静的 MkDocs (Material) 静的HTML Docusaurus SPA VitePress SPA Sphinx Hugo Astro (Starlight) mdBook 静的HTML 静的HTML 静的HTML 静的HTML は高度なUIが実現可能 PDF化が難しい SPAは配置先が限定される可能性が ある（後述） SPA

サイトPDF化をサポートするか？ プロダクト サイトPDF MkDocs (Material) ◎ プラグイン充実 Docusaurus △ 外部ツール VitePress △ 外部ツール Sphinx ◎ 標準機能 Hugo ✕ 実質なし Astro (Starlight) △ 外部ツール mdBook ○ プラグインあり 化は必須要件か？ 化が必須な 場合 や が正確に描画でき るか？ - PDF - PDF - Mermaid SVG

や が正確に描画されるか？ Mermaid SVG の表示はJavaScriptでのレンダリングが一般的 Webでは問題ないが、PDF化時にはレンダリングされない 同様にSVGは作成方法によってブラックアウトされ表示されないことがある Mermaid

によるMermaidの解決 MkDocs mkdocs-kroki-plugin 外部サービスを利用する場合、機密情報を扱えない Krokiサーバーを運用する必要がある mkdocs-export-mermaid-to-svg レンダリングエンジンが古い プレビュー時もSVG変換が発生し重い

というわけで、作りました

mkdocs-mermaid-to-svg @mermaid-js/mermaid-cli の利用 を に変換し、Mermaidブロックを置換 ローカル変換 有効化スイッチあり Mermaid SVG

のブラックアウト問題 SVG を記述するためdraw.ioを利用 WeasyPrintによるPDF化との相性が悪い foreignObjectなどが正しくレンダリングされない PNGで出力する方法もあるが、品質が落ちる SVG

というわけで、作りました

mkdocs-svg-to-png を に変換する拡張機能 PDF変換時のみSVGをPNGに変換 SVG PNG

サイトPDF化をサポートするか？ プロダクト サイトPDF MkDocs (Material) ◎ プラグイン充実 Docusaurus △ 外部ツール VitePress △ 外部ツール Sphinx ◎ 標準機能 Hugo ✕ 実質なし Astro (Starlight) △ 外部ツール mdBook ○ プラグインあり 化は必須要件か？ 化が必須な 場合 や が正確に描画でき るか？ - PDF - PDF - Mermaid SVG

静的サイトジェネレーターの選択に戻る

テーマのTPO 技術文書向けのテーマがあるか？ サイドメニューが階層構造をサポートしているか？ 大量の文書を扱うのに適しているか？ テーマがカスタマイズしやすいか？

ホスティング先 静的サイトがホスティングできるサービスなら基本的にどこでもいい 自分たちの身近なサービスを選択するのもポイント SPAの場合は、配置先が限定される可能性がある 非公開化の要件があるか？ 認証・認可の要件があるか？

私たちの選定 項目 GitHub Pages Azure Static Web Apps Azure Blob Storage SPA対応 ○ ○ × 非公開化 なし Private Endpoint（要Standard） Private Endpoint GitHub権限 認証・認可 組み込み(25名)※ 別サービス連携 要GHEC ステージング環境 × ○ △ ステージング上限 0 Free: 3 / Standard: 10 実装次第（実質上限なし） 複数リポジトリ × × △ 約2,700円/月 約2,500円/月+ストレージ操作他 月額目安 0円/月 Standard+PE PE*2(web+blob) ※ カスタムも可能だが、ステージングと併用は弊害を伴うため一旦除外

という訳で作りました

swa-github-role-sync https://github.com/genai-docs/swa-github-role-sync の任意のリポジトリーのユーザーとSWAの組み込み認証のユーザーを同期 GitHub する で定期的に実行する GitHub Actions

• https://github.com/genai-docs/swa-github-role-sync

やめてBlob Storageに移行しました SWA

Azure Blob Storage の選定理由 項目 Azure Static Web Apps Azure Blob Storage SPA対応 ○ × 非公開化 Private Endpoint（要Standard） Private Endpoint 認証・認可 組み込み(25名)※ 別サービス連携 ステージング環境 ○ △ ステージング上限 Free: 3 / Standard: 10 実装次第（実質上限なし） 複数リポジトリ × △ 約 2,700円/月 約 2,500円/月+ストレージ他 月額目安 Standard+PE PE*2(web+blob)

そろそろ次のネタが読めましたか？

というわけで、作りました

azure-blob-storage-site-deploy https://github.com/nuitsjp/azure-blob-storage-site-deploy に静的サイトをデプロイするGitHub Action マルチリポジトリー対応 マルチブランチ対応 無限ステージング対応 PRコメントにステージングURLを自動で返信 PRクローズでステージング削除 超低コスト運用（月額約2,500円+ストレージ操作他） Azure Blob Storage

• https://github.com/nuitsjp/azure-blob-storage-site-deploy

azure-blob-storage-site-deploy のフォルダ構成

保守ステージのコスト0 保守ステージではGitHub Pagesを利用する Azure Blob Storageに相乗りしてアクティブプロジェクトに払わせる

まとめ

ドキュメントの2つの課題 ドキュメント体系 ドキュメント基盤

ドキュメント基盤要件 人間 & AIフレンドリー ブラウザー閲覧 単一PDF出力 単純な図の簡便な作成 複雑な図を正確に描画 表の簡便な作成 管理 PRベースレビュー PR時のステージング git CI/CD 検索を含めた高い閲覧性 高い拡張性 十分なセキュリティ 低コスト 保守ステージのコスト0

リンク集 コンテンツ デモにも利用したフルセットのサンプルリポジトリ mkdocs-mermaid-to-svg mkdocs-svg-to-png swa-github-role-sync azure-blob-storage-site-deploy コミュニティ C# Tokyo - https://csharp-tokyo.connpass.com/ ラボ - .NET

• https://github.com/genai-docs/genai-mkdocs-sample
• https://github.com/nuitsjp/mkdocs-mermaid-to-svg
• https://github.com/nuitsjp/mkdocs-svg-to-png
• https://github.com/genai-docs/swa-github-role-sync
• https://github.com/nuitsjp/azure-blob-storage-site-deploy
• https://csharp-tokyo.connpass.com/
• https://dotnetlab.connpass.com/

ご清聴ありがとうございました