Docusaurus を使った開発ドキュメントの作成と運用

2024/03/29 第14回LTラジオ

Transcript

1. Docusaurus を使った 開発ドキュメントの作成と運⽤ 第14回LT練習会 Yudai Yamamoto (@_yy616)
2. 👦 ⾃⼰紹介 ⼭本 雄⼤ (yamamoto yudai) フロントエンドエンジニア - サイボウズ株式会社 - 新卒（2024/3/29 時点） - AI、⽣産性向上、デザイン ＠_yy616 最近は⼤規模⾔語モデルを フルスクラッチで作るPJ（東⼤松尾研 GENIAC）に参画中
3. Q. ドキュメント書いてますか︖メンテナンスできてますか︖
4. Q. ドキュメント書いてますか︖メンテナンスできてますか︖ ドキュメント管理についてはどの組織も少なからず苦労しているはず
5. 推しのドキュメント管理ツールと その運⽤について話します💪
6. 🗒 ドキュメント管理ツールは群雄割拠 組織、チームによってツールがバラバラでどれが良いのか悩ましい
7. ✅ 個⼈的ドキュメント管理ツールの要件 1. マークダウンで書ける 2. 検索機能を備えている 3. バージョン（Git）管理できる 4. レビュープロセスを実施しやすい 書きやすさ 👉 参照容易性 👉 メンテナンス性 👉 品質 👉
8. 🦖 選ばれたのは Docusaurus でした 2023/10 にバージョン3がリリース
9. 概要 • Meta によって公開されているオープンソースの静的サイトジェネレーター • 技術ドキュメントの作成に特化しており、マークダウンの記述のみでコンテンツを追加できる 🤔 Docusaurus is 何︖ 特徴 • MDX で編集可能 • エンジニアフレンドリーな UI • 検索機能 • バージョン管理機能 • i18n サポート
10. 🙌 こんな感じの良さげな wiki が⼿軽に作れる
11. 以降はチームで実際に運⽤した話 Docusaurus ⾃体ではなくそれを使った運⽤の話
12. 通常の開発と同じようにレビュープロセスを踏み、実装と同じタイミングで ドキュメントも追加する 🧭 運⽤⽅針1 あとでドキュメント追加するタイミングは⼤体来ないので実装と合わせて追加・更新 実際のドキュメント追加のPR
13. フロー型情報は Confluence や GitHub Issue、ストック型情報は Docusaurus で管理する 全てのドキュメントを Docusaurus 上で管理するのはきつい 👉 ストックしても効果が薄い情報（フロー型情報）は管理しない 🧭 運⽤⽅針2 調査ログ 個別タスクの実装⽅針 MTGの議事録 など 環境構築 リリースの⼿順書 設計資料 アプリ仕様書 など フロー型情報 ストック型情報 賞味期限が短い or コードから辿れれば良いだけの情報 賞味期限が⻑い情報 or 仕様に関する情報
14. ✅ その他メンテナンス上の⼯夫 • ドキュメントの種類別にテンプレートを⽤意する • ドキュメント更新のチェックリストをPRのテンプレに加える • マークアップ系の Linter を使う • 更新防⽌⽤のワークフローを⽤意する PRのチェックリスト 更新チェック⽤のワークフロー
15. 📝 まとめ • 開発系のドキュメント管理には Docusaurus がおすすめ • Docusaurus を使うことでメンテナンス性が向上 • 他のドキュメントツールと併⽤したり、LinterやCIを活⽤したりすることで⽣産性Up
16. ご清聴ありがとうございました🙇