GitHubとVitePressによる 開発ドキュメント運用 / escape-document-death

これは「ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT - connpass」（ https://findy.connpass.com/event/302508/ ）で登壇したスライドです。

元データは以下のRepositoryにあります。
https://github.com/YuheiFUJITA/slide-20231206-findy

Transcript

1. GitHub とVitePress による 開発ドキュメント運用 Yuhei FUJITA 2023-12-06@Findy
2. 2 / 19
3. 3 / 19 自己紹介 名前: Yuhei FUJITA （藤田 悠平） X(Twitter): @Yuhei_FUJITA GitHub: @YuheiFUJITA 所属: 株式会社バリューデザイン / アララ株式会社 業務: 主に開発 コミュニティ運営: Vue Fes / PWA Night / VS Code Meetup 趣味: キャンプ / フィルムカメラ
4. 4 / 19 会社紹介 なんか話す
5. 5 / 19 そもそもなぜドキュメントは 陳腐化するのか？ ドキュメントの重要性は理解しているのに…
6. 6 / 19 陳腐化する理由 1. 議論と更新が別れているから すべての議論が終わってから更新しようとする テストコードを後から書くのと同じ 2. ドキュメントの更新コストが大きいから Excel 方眼紙やパワポのスライドは楽に見えて編集が大変 バージョン管理まで考えると更新が面倒になる 3. 直近の自分たちは困らないから 記憶が新しいうちはドキュメントを見なくてもある程度はできる ドキュメントが活きてくるのは後から
7. 7 / 19 今まで見てきたよくないドキュメント 1. 読めない Excel 方眼がメンテされなくなって文字がはみ出してる… なぜかパワポで作られた激重のスライド… 2. 見つからない Google ドライブで検索したら似たファイルが大量にヒット… ファイル形式によって管理場所が違う… 3. 知らない間に更新されている Pull Request を作成しているうちに仕様が変わっていた… 共同編集のせいでファイルの変更履歴が最早カオス…
8. 8 / 19 良いドキュメントとは 何なのか？
9. 9 / 19 良いドキュメントの条件 1. 更新が容易であること ドキュメントの更新をしたいのであって見た目を調整したいわけではない ファイルサイズが大きくなって重たいファイルは誰も開きたくない 2. 可読性が高いこと ドキュメントは書く時間/ 人数よりも読む時間/ 人数のほうがが圧倒的に多い 読みやすいドキュメントは理解もしやすい 3. 履歴に経緯が紐づいていること 「なぜこの仕様になったのか」はドキュメントだけでは読み取れない その使用になった経緯がわからないと次変更するときに判断が難しい
10. 10 / 19 ドキュメントは 書くためでも 更新するためでもなく 未来の誰かが読むためにある
11. 11 / 19 Markdown + GitHub + VitePress
12. 12 / 19 VitePress Markdown から ドキュメントサイトを生成 静的サイトホスティングで 公開できる Markdown 拡張で カスタマイズできる Vue.js でカスタマイズできる VitePress Vite & Vue Powered Static Site Generator Simple, powerful, and fast. Meet the modern SSG framework you've always wanted. Get Started View on GitHub VitePress
13. 13 / 19 VitePress の使い方 1. プロジェクトの作成 2. VitePress のインストール 3. VitePress の初期化 4. ローカルサーバーの起動 1 npm init 1 npm add -D vitepress 1 npx vitepress init 1 npm run docs:dev
14. 14 / 19 フォーマットにMarkdown を採用した理由 1. git との相性が良い テキストベースなので差分がわかりやすい git diff を見れば変更内容がわかる 2. 書くことに専念できる フォーマットやスタイルを気にする必要がない Word の改ページのような本来意識しなくてよいことから開放される 3. CI を組み込める textlint やPrettier などのツールを使って自動でチェックできる 表記ゆれなども一元管理できる ` `
15. 15 / 19 管理方法にGitHub を採用した理由 1. Issue/Pull Request 駆動のドキュメント更新 Issue/Pull Request を議論の場にできる Issue/Pull Request のコメントがそのまま変更の経緯として紐づく 2. Release Note によるバージョン管理 Pull Request をまとめることで差分の概要がわかりやすい ファイル名にバージョンをつけて管理する運用から脱却できる 3. GitHub による従来の開発体験の継承 新しい知識が不要なので導入が容易 コーディングと同じフローを踏める
16. 16 / 19 生成ツールにVitePress を採用した理由 1. 運用コストがほぼゼロ GitHub Pages やS3 + Cloud Front でホスティングできる 2. 拡張性が高い markdown-it を使ってMarkdown の拡張ができる Vue.js でカスタマイズできる 3. 標準で必要十分な機能が揃っている Algolia と連携して検索機能が使える git/GitHub との連携が便利（更新日時の表示など） 最近AI Chat 機能が追加された ` `
17. 17 / 19 🔰 📖 📖 📖 タスク管理アプリ ドキュメント VitePressによるドキュメント管理サンプル はじめに メンバー タスク管理アプリ Home OpenAPI Figma 環境一覧 Repository
18. 18 / 19 課題 1. git/GitHub の知識が必要 企画や営業などの非エンジニアにはハードルが高い 2. すべてをVitePress で解決できるわけではない Markdown で表現しきれないドキュメントは別途用意する必要がある 3. 最低限のルール作りは必要 「急ぎだから main に直接コミットして」とかし始めると崩壊する 口頭による議論は結局残らない ` `
19. 19 / 19 まとめ Markdown + GitHub + VitePress とドキュメントは相性がよさそう 書きやすさ・管理のしやすさ・読みやすさがいい感じ これですべてを解決できるわけではない 無理にこの方法にこだわる必要はない 技術者目線にかなり偏っている点には注意 ドキュメントの最終目的は読まれること 書いて更新して終わりではない 未来の誰かが読むために書く