ドキュメントサイト生成フレームワークのすゝめ

Transcript

1. ドキュメントサイト生成フレームワークのすゝめ ソフトウェア品質を守るドキュメント戦略
2. 自己紹介 KDDIアジャイル開発センター株式会社 データエンジニア　篠原　誠 KDDI株式会社入社後、KDDIアジャイル開発センター株式会社に出向 チャットボット開発や統計化位置情報分析基盤開発、KDDI研究所での対話AIプロジェクト参加などを経て、 現在はデータエンジニアとしてデータクリーンルームの開発に従事
3. ソフトウェア or システムのドキュメントどうやって書いていますか？
4. よくあるドキュメントを書く場所 📄 Google Docs 📄 Confluence 📄 Notion 📄 OneNote
5. コードを書く場所とドキュメントを書く場所が分かれていると… ドキュメントが陳腐化しやすい ドキュメントが見つからない モチベが下がる といったことが起きがち
6. 1つの解決策として： ドキュメントとソースコードの統合
7. ドキュメントもコードベースに組み込んじゃおう リポジトリ構造例 ✅ ドキュメントとソースコードの一元管理 コードとドキュメントの一貫性が保たれやすい → コード変更時にドキュメントも同時に更新でき るため、ドキュメントの陳腐化を防げる コードとドキュメントを同じPRでレビューできる ✅ CI/CD連携 ドキュメント更新の自動化 APIスキーマの自動更新 FastAPIのようなAPIスキーマを自動生成するフ レームワークを利用すればドキュメントのAPI スキーマも自動更新できる project-root/ ├── src/ │ └── payment/ │ ├── controller.ts │ └── service.ts | └── ... ├── docs/ │ └── payment/ │ ├── api.md │ └── workflow.md | └── ... ├── package.json └── ...
8. ドキュメント生成フレームワーク比較 SSGツール フレームワーク 特徴 Docusaurus React Meta社製 VitePress Vue Vite+Vueで作られてる MkDocs Python お手軽度は高い Nextra Next.js Next.jsで作られてる Starlight Astro Astroで作られてる Markdoc Stripe Stripe社製
9. ドキュメントサイト生成フレームワーク選定のポイント Github Star数も参考に
10. ドキュメントサイト生成フレームワーク選定のポイント カスタマイズ性があるか React/Vue/Astroなどのフレームワークを使っているドキュメントサイト生成フレームワークは ドキュメント内にコンポーネントを埋め込むことができる チームの技術スタックにあったものを選ぶ ドキュメントサイト生成フレームワークが拠り所にしているフレームワークが チームの技術スタックと合っていれば、比較的導入がスムーズ Nextra: Next.js Docusaurus: React VitePress: Vue MkDocs: Python Starlight: Astro 最終的にはフィーリングも重要
11. 色んなサイトを見てみよう React Flow - Nextra React Native - Docusaurus MkDocs - MkDocs Pinia - VitePress
12. 最高のドキュメントは 生きたコードと共に呼吸する 「コードがドキュメントであり ドキュメントがコードである状態」 みつを