開発ドキュメントの管理・閲覧に VitePress を使ってみて感じた良かった点と注意点 / document-with-vitepress

Transcript

1. 開発ドキュメントの運用に VitePress を使ってみて感じた 良かった点と注意点 フロントエンドカンファレンス沖縄2022 | 2022/11/26 | Yuhei FUJITA
2. フロントエンドの カンファレンスだし Slidev でスライド作ってみたよ
3. 自己紹介 名前 Yuhei FUJITA 藤田 悠平 Twitter @Yuhei_FUJITA 最近の活動 カンファレンススタッフ - Vue Fes - PWA Night Conference - VS Code Conference 所属 アララ株式会社 https://www.arara.com 好きな言語 フレームワーク TypeScript, Vue.js
4. 今日のテーマは ドキュメント管理
5. ドキュメント管理でありがちなこと 保存場所がバラバラ どこに仕様書あるんだよ、ファイル名どれだよ 「要件定義書」で検索したら大量にヒットしたけどどれだよ フォーマットが統一されてない Google ドキュメントとWord 混在するのやめてくれ なんだろう、要件定義書をスライドで作って満足するのやめてもらっていいですか？ Excel 方眼（笑） どれが最新で変更点が何かわからない おい誰だよ黙って仕様書変更したの聞いてないぞ この「◦◦のコピー」ってなんや… ※ これはフィクションではありません。
6. そもそも好き勝手出来るのが 良くない
7. ドキュメント管理に求める要件 フォーマットの統一 自由度を必要以上に与えたくない Markdown + αくらいの表現力があれば十分 更新履歴の管理 いつ・どう変更されたかをシステマティックに残したい 更新履歴の管理にコストをかけたくない ドキュメントの一覧性 管理方法を統一したい 「ここを見れば必要なものだけが全てある」状態にしたい 最低限必要と思った要件
8. そこで使ってみたのがVitePress
9. Vite: The DX that can't be beat Feel the speed of Vite. Instant server start and lightning fast HMR that stays fast regardless of the app size. VitePress Vite & Vue Powered Static Site Generator Simple, powerful, and performant. Meet the modern SSG framework you've always wanted. Get Started View on GitHub VitePress VitePress とは Markdown からSSG できる Markdown でドキュメントサイトが作れる 静的サイトとして公開できる Vue.js ベース Vue.js のComponent が使える VuePress の後継 Vite によって高速化された 現在（2022/11/19 ）はまだAlpha 版 VuePress のようなPlugin は未実装
10. セットアップは簡単 1. プロジェクトを作成 2. Vitepress をインストール 3. package.json に追記 4. ディレクトリ構成を作成 5. ローカルで起動 yarn init yarn add --dev vitepress vue ` ` "scripts": { "docs:dev": "vitepress dev docs", "docs:build": "vitepress build docs", "docs:serve": "vitepress serve docs" }, { "devDependencies": { "vitepress": "^1.0.0-alpha.4", "vue": "^3.2.37" } } . ├─ docs │ ├─ .vitepress │ │ └─ config.js │ └─ index.md └─ package.json yarn dev
11. 実際に作ってみた
12. TOP ページ 全体の概要 新規メンバーが最初に見る画面 プロダクトそのものやチーム構成
13. 新規メンバー向け情報 環境構築や開発手順などをまとめる 新規メンバーが入ったときはここ見せたらOK
14. ドキュメント類 要件定義〜UML まで テキストベースのドキュメント Figma のようなテキストベースでないものは別管理 OAS なども別管理
15. 実際に使ってみてよかった点
16. ランニングコストが ほとんどかからない Netlify, Vercel, AWS Amplify, Cloudflare Pages, Render GitHub Pages GitLab Pages Azure Static Web Apps Firebase Surge Heroku Layer0 Markdown 拡張が豊富 手順書で役立つCode Blocks Line Highlighting in Code Blocks markdown-it のplugin で拡張出来る markdown-it-plantuml でPlantUML も使える Static Site Hosting できればよい 標準のMarkdown だけでは不足する表現が可能
17. すべてをGit 管理出来る バージョン管理はやはりGit が楽 勝手な更新がされにくい GitHub をフル活用出来る Issue ベースで管理できる 変更の経緯がPR やIssue として残る ドキュメントもソースコード同様Git 管理が安心・安 全 使い慣れたGitHub で管理できるのは学習・運用コスト がかからない
18. 実際に使ってみて困ったこと
19. 同時編集は厳しい ディスカッションしながら書くには向いてない ある程度落ち着けばIssue 上げて修正していくで よい Google ドキュメントみたいに共同編集できない 大枠決まるまではこっちで下書きしたほうが 楽？ Git(GitHub) が必須 GitHub Teams 使うなら有料 このためだけにアカウント追加するのは… 要件定義や設計は技術者だけとは限らない 企画や営業にGit 使わせるのは酷
20. 【結論】 課題は残るが問題解決 VitePress とても良い