ドキュメント基盤¶

生成AIの活用が進み、ドキュメントの重要性が再認識されています。

AWSからはKiro、GitHubからはSpec Kitも登場し、仕様駆動開発が注目を集めています。

しかし、これらをプロダクトレベルで運用するには多くの課題が存在します。

図表は何で描くか？チームで共有するには？顧客への提出が必要なときPDF化は可能か？プレゼン資料は？

本サイトでは、仕様駆動開発を支えるドキュメント基盤のインフラストラクチャーを包括的に紹介します。

私たちは、生成AIが注目を集める前からこれまで7年間、Office文書からMarkdownベースへの仕様書へ移行してきました。

その間に多くの課題に直面し、それらを解決するために多くの工夫を重ねました。

これまでに得た多くの実践的なノウハウを、生成AI時代の視点から共有いたします。

外部リソース¶

技術スタック¶

Markdown
MkDocs(Material for MkDocs): 静的サイトジェネレーター
Mermaid: 図表作成ライブラリ
Draw.io（diagrams.net）: SVG描画ツール
Marp: Markdownプレゼンテーションツール

利用サービス・ツール¶

Coding Agent（Codex CLI, Claude Code, GitHub Copilotなど）
GitHub
- GitHub Actions
Azure Static Web Apps
- swa-github-repo-auth
Visual Studio Code
- Draw.io Integration
- テキスト校正くん
MkDocs
- Python
- uv
- mkdocs-mermaid-to-svg
- mkdocs-svg-to-png
- mkdocs-to-pdf
- mkdocs-table-reader-plugin
Marp
- Node.js
Excel
- CopyToMarkdownAddIn

以下、T.B.D

🚀 セットアップ¶

前提条件¶

Windows 10/11
PowerShell 5.1 以上
インターネット接続（パッケージダウンロード用）

自動セットアップ¶

管理者権限でPowerShellを起動し、以下のコマンドを実行してください：

.\scripts\Setup-Environments.ps1

このスクリプトは以下を自動でインストール・セットアップします：

Python 3.13
uv（Python環境管理）
Node.js
Mermaid CLI
GTK+ Runtime（PDF生成用）
プロジェクト依存関係

手動セットアップ¶

リポジトリのクローン

git clone <repository-url>
cd DocumentationStrategy

Python環境のセットアップ
```
uv sync
```
開発サーバーの起動
```
uv run mkdocs serve
```
ブラウザでアクセス
```
http://localhost:8000
```

📝 使用方法¶

ローカル開発¶

# 開発サーバー起動
uv run mkdocs serve

# 本番ビルド
uv run mkdocs build

# PDF生成
uv run mkdocs build --config-file mkdocs.yml

ドキュメント編集¶

docs/ ディレクトリ内のMarkdownファイルを編集
Mermaid図表は、コードブロック内で mermaid 言語を指定
変更は自動的にライブリロードで反映

新しい図表の追加¶

![SVG Diagram](assets/images/index_mermaid_0_e20df388.png){#mermaid-diagram-index-1}

📁 プロジェクト構造¶

DocumentationStrategy/
├── docs/                          # ドキュメントソース
│   ├── 01.システム設計/           # システム設計関連
│   ├── プロセス・フロー/          # プロセス図表
│   ├── プロジェクト管理/          # プロジェクト管理図表
│   ├── stylesheets/               # カスタムCSS
│   └── index.md                   # トップページ
├── scripts/                       # セットアップスクリプト
├── mkdocs.yml                     # MkDocs設定
├── pyproject.toml                 # Python依存関係
└── README.md                      # このファイル

🔧 設定¶

MkDocs設定（mkdocs.yml）¶

主要な設定項目：

テーマ: Material for MkDocs（日本語対応）
プラグイン:
mermaid-to-image: PDF出力用の図表変換
to-pdf: PDF生成機能
拡張機能: Mermaid図表サポート、コードハイライト

Python依存関係（pyproject.toml）¶

MkDocs関連パッケージ
PDF生成用ライブラリ（WeasyPrint）
Mermaid図表処理プラグイン

📄 PDF出力¶

ビルド時に自動的にPDFが生成されます：

uv run mkdocs build

生成されたPDF: site/pdf/ドキュメンテーション戦略.pdf

🤝 コントリビューション¶

このリポジトリをフォーク
フィーチャーブランチを作成
変更をコミット
プルリクエストを送信

📜 ライセンス¶

MIT License - 詳細は LICENSE ファイルを参照してください。

🆘 トラブルシューティング¶

よくある問題¶

PDF生成エラー
- GTK+ Runtimeがインストールされているか確認
- WeasyPrintの依存関係を確認
Mermaid図表が表示されない
- ブラウザのキャッシュをクリア
- JavaScriptが有効になっているか確認
セットアップスクリプトが動作しない
- PowerShellを管理者権限で実行
- ExecutionPolicyを確認

サポート¶

問題が発生した場合は、GitHubのIssuesで報告してください。