Slide 1

Slide 1 text

開発ドキュメントの運用に VitePress を使ってみて感じた 良かった点と注意点 フロントエンドカンファレンス沖縄2022 | 2022/11/26 | Yuhei FUJITA

Slide 2

Slide 2 text

フロントエンドの カンファレンスだし Slidev でスライド作ってみたよ

Slide 3

Slide 3 text

自己紹介 名前 Yuhei FUJITA 藤田 悠平 Twitter @Yuhei_FUJITA 最近の活動 カンファレンススタッフ - Vue Fes - PWA Night Conference - VS Code Conference 所属 アララ株式会社 https://www.arara.com 好きな言語 フレームワーク TypeScript, Vue.js

Slide 4

Slide 4 text

今日のテーマは ドキュメント管理

Slide 5

Slide 5 text

ドキュメント管理でありがちなこと 保存場所がバラバラ どこに仕様書あるんだよ、ファイル名どれだよ 「要件定義書」で検索したら大量にヒットしたけどどれだよ フォーマットが統一されてない Google ドキュメントとWord 混在するのやめてくれ なんだろう、要件定義書をスライドで作って満足するのやめてもらっていいですか? Excel 方眼(笑) どれが最新で変更点が何かわからない おい誰だよ黙って仕様書変更したの聞いてないぞ この「○○のコピー」ってなんや… ※ これはフィクションではありません。

Slide 6

Slide 6 text

そもそも好き勝手出来るのが 良くない

Slide 7

Slide 7 text

ドキュメント管理に求める要件 フォーマットの統一 自由度を必要以上に与えたくない Markdown + αくらいの表現力があれば十分 更新履歴の管理 いつ・どう変更されたかをシステマティックに残したい 更新履歴の管理にコストをかけたくない ドキュメントの一覧性 管理方法を統一したい 「ここを見れば必要なものだけが全てある」状態にしたい 最低限必要と思った要件

Slide 8

Slide 8 text

そこで使ってみたのがVitePress

Slide 9

Slide 9 text

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 は未実装

Slide 10

Slide 10 text

セットアップは簡単 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

Slide 11

Slide 11 text

実際に作ってみた

Slide 12

Slide 12 text

TOP ページ 全体の概要 新規メンバーが最初に見る画面 プロダクトそのものやチーム構成

Slide 13

Slide 13 text

新規メンバー向け情報 環境構築や開発手順などをまとめる 新規メンバーが入ったときはここ見せたらOK

Slide 14

Slide 14 text

ドキュメント類 要件定義〜UML まで テキストベースのドキュメント Figma のようなテキストベースでないものは別管理 OAS なども別管理

Slide 15

Slide 15 text

実際に使ってみてよかった点

Slide 16

Slide 16 text

ランニングコストが ほとんどかからない 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 だけでは不足する表現が可能

Slide 17

Slide 17 text

すべてをGit 管理出来る バージョン管理はやはりGit が楽 勝手な更新がされにくい GitHub をフル活用出来る Issue ベースで管理できる 変更の経緯がPR やIssue として残る ドキュメントもソースコード同様Git 管理が安心・安 全 使い慣れたGitHub で管理できるのは学習・運用コスト がかからない

Slide 18

Slide 18 text

実際に使ってみて困ったこと

Slide 19

Slide 19 text

同時編集は厳しい ディスカッションしながら書くには向いてない ある程度落ち着けばIssue 上げて修正していくで よい Google ドキュメントみたいに共同編集できない 大枠決まるまではこっちで下書きしたほうが 楽? Git(GitHub) が必須 GitHub Teams 使うなら有料 このためだけにアカウント追加するのは… 要件定義や設計は技術者だけとは限らない 企画や営業にGit 使わせるのは酷

Slide 20

Slide 20 text

【結論】 課題は残るが問題解決 VitePress とても良い