Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Yuhei FUJITA
November 19, 2022

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

Yuhei FUJITA

November 19, 2022
Tweet

More Decks by Yuhei FUJITA

Other Decks in Programming

Transcript

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    これはフィクションではありません。

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  8. そこで使ってみたのがVitePress

    View full-size slide

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

    View full-size slide

  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

    View full-size slide

  11. 実際に作ってみた

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  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
    だけでは不足する表現が可能

    View full-size slide

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

    使い慣れたGitHub
    で管理できるのは学習・運用コスト
    がかからない

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide