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

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

Yuhei FUJITA
December 06, 2023

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

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

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

Yuhei FUJITA

December 06, 2023
Tweet

More Decks by Yuhei FUJITA

Other Decks in Programming

Transcript

  1. GitHub
    とVitePress
    による
    開発ドキュメント運用
    Yuhei FUJITA
    2023-12-06@Findy

    View full-size slide

  2. 3 / 19
    自己紹介
    名前: Yuhei FUJITA
    (藤田 悠平)
    X(Twitter): @Yuhei_FUJITA
    GitHub: @YuheiFUJITA
    所属:
    株式会社バリューデザイン /
    アララ株式会社
    業務:
    主に開発
    コミュニティ運営: Vue Fes / PWA Night / VS Code
    Meetup
    趣味:
    キャンプ /
    フィルムカメラ

    View full-size slide

  3. 4 / 19
    会社紹介
    なんか話す

    View full-size slide

  4. 5 / 19
    そもそもなぜドキュメントは
    陳腐化するのか?
    ドキュメントの重要性は理解しているのに…

    View full-size slide

  5. 6 / 19
    陳腐化する理由
    1.
    議論と更新が別れているから
    すべての議論が終わってから更新しようとする
    テストコードを後から書くのと同じ
    2.
    ドキュメントの更新コストが大きいから
    Excel
    方眼紙やパワポのスライドは楽に見えて編集が大変
    バージョン管理まで考えると更新が面倒になる
    3.
    直近の自分たちは困らないから
    記憶が新しいうちはドキュメントを見なくてもある程度はできる
    ドキュメントが活きてくるのは後から

    View full-size slide

  6. 7 / 19
    今まで見てきたよくないドキュメント
    1.
    読めない
    Excel
    方眼がメンテされなくなって文字がはみ出してる…
    なぜかパワポで作られた激重のスライド…
    2.
    見つからない
    Google
    ドライブで検索したら似たファイルが大量にヒット…
    ファイル形式によって管理場所が違う…
    3.
    知らない間に更新されている
    Pull Request
    を作成しているうちに仕様が変わっていた…
    共同編集のせいでファイルの変更履歴が最早カオス…

    View full-size slide

  7. 8 / 19
    良いドキュメントとは
    何なのか?

    View full-size slide

  8. 9 / 19
    良いドキュメントの条件
    1.
    更新が容易であること
    ドキュメントの更新をしたいのであって見た目を調整したいわけではない
    ファイルサイズが大きくなって重たいファイルは誰も開きたくない
    2.
    可読性が高いこと
    ドキュメントは書く時間/
    人数よりも読む時間/
    人数のほうがが圧倒的に多い
    読みやすいドキュメントは理解もしやすい
    3.
    履歴に経緯が紐づいていること
    「なぜこの仕様になったのか」はドキュメントだけでは読み取れない
    その使用になった経緯がわからないと次変更するときに判断が難しい

    View full-size slide

  9. 10 / 19
    ドキュメントは
    書くためでも
    更新するためでもなく
    未来の誰かが読むためにある

    View full-size slide

  10. 11 / 19
    Markdown
    +
    GitHub
    +
    VitePress

    View full-size slide

  11. 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

    View full-size slide

  12. 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

    View full-size slide

  13. 14 / 19
    フォーマットにMarkdown
    を採用した理由
    1. git
    との相性が良い
    テキストベースなので差分がわかりやすい
    git diff
    を見れば変更内容がわかる
    2.
    書くことに専念できる
    フォーマットやスタイルを気にする必要がない
    Word
    の改ページのような本来意識しなくてよいことから開放される
    3. CI
    を組み込める
    textlint
    やPrettier
    などのツールを使って自動でチェックできる
    表記ゆれなども一元管理できる
    ` `

    View full-size slide

  14. 15 / 19
    管理方法にGitHub
    を採用した理由
    1. Issue/Pull Request
    駆動のドキュメント更新
    Issue/Pull Request
    を議論の場にできる
    Issue/Pull Request
    のコメントがそのまま変更の経緯として紐づく
    2. Release Note
    によるバージョン管理
    Pull Request
    をまとめることで差分の概要がわかりやすい
    ファイル名にバージョンをつけて管理する運用から脱却できる
    3. GitHub
    による従来の開発体験の継承
    新しい知識が不要なので導入が容易
    コーディングと同じフローを踏める

    View full-size slide

  15. 16 / 19
    生成ツールにVitePress
    を採用した理由
    1.
    運用コストがほぼゼロ
    GitHub Pages
    やS3 + Cloud Front
    でホスティングできる
    2.
    拡張性が高い
    markdown-it
    を使ってMarkdown
    の拡張ができる
    Vue.js
    でカスタマイズできる
    3.
    標準で必要十分な機能が揃っている
    Algolia
    と連携して検索機能が使える
    git/GitHub
    との連携が便利(更新日時の表示など)
    最近AI Chat
    機能が追加された
    ` `

    View full-size slide

  16. 17 / 19
    🔰 📖 📖 📖
    タスク管理アプリ
    ドキュメント
    VitePressによるドキュメント管理サンプル
    はじめに メンバー
    タスク管理アプリ Home OpenAPI Figma 環境一覧 Repository

    View full-size slide

  17. 18 / 19
    課題
    1. git/GitHub
    の知識が必要
    企画や営業などの非エンジニアにはハードルが高い
    2.
    すべてをVitePress
    で解決できるわけではない
    Markdown
    で表現しきれないドキュメントは別途用意する必要がある
    3.
    最低限のルール作りは必要
    「急ぎだから main
    に直接コミットして」とかし始めると崩壊する
    口頭による議論は結局残らない
    ` `

    View full-size slide

  18. 19 / 19
    まとめ
    Markdown + GitHub + VitePress
    とドキュメントは相性がよさそう
    書きやすさ・管理のしやすさ・読みやすさがいい感じ
    これですべてを解決できるわけではない
    無理にこの方法にこだわる必要はない
    技術者目線にかなり偏っている点には注意
    ドキュメントの最終目的は読まれること
    書いて更新して終わりではない
    未来の誰かが読むために書く

    View full-size slide