Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Docusaurus を使った開発ドキュメントの作成と運用
Search
yudai yamamoto
March 29, 2024
0
470
Docusaurus を使った開発ドキュメントの作成と運用
2024/03/29 第14回LTラジオ
yudai yamamoto
March 29, 2024
Tweet
Share
More Decks by yudai yamamoto
See All by yudai yamamoto
安全性を高めるAzure AI Content Safety について
yyo616
1
260
コンテンツモデレーション入門の入門
yyo616
2
150
2024年における生成AIエンジニアとは何者か
yyo616
11
3.7k
大規模言語データの前処理とLLM-as-a-Judge の活用
yyo616
4
1.4k
Playwrightでテストを楽に実装したい
yyo616
0
61
Featured
See All Featured
Into the Great Unknown - MozCon
thekraken
34
1.6k
[Rails World 2023 - Day 1 Closing Keynote] - The Magic of Rails
eileencodes
33
2k
Large-scale JavaScript Application Architecture
addyosmani
510
110k
Performance Is Good for Brains [We Love Speed 2024]
tammyeverts
7
590
Done Done
chrislema
182
16k
Side Projects
sachag
452
42k
Building Applications with DynamoDB
mza
93
6.2k
Gamification - CAS2011
davidbonilla
80
5.1k
Save Time (by Creating Custom Rails Generators)
garrettdimon
PRO
29
980
Scaling GitHub
holman
459
140k
Optimizing for Happiness
mojombo
376
70k
Documentation Writing (for coders)
carmenintech
67
4.6k
Transcript
Docusaurus を使った 開発ドキュメントの作成と運⽤ 第14回LT練習会 Yudai Yamamoto (@_yy616)
👦 ⾃⼰紹介 ⼭本 雄⼤ (yamamoto yudai) フロントエンドエンジニア - サイボウズ株式会社 -
新卒(2024/3/29 時点) - AI、⽣産性向上、デザイン @_yy616 最近は⼤規模⾔語モデルを フルスクラッチで作るPJ(東⼤松尾研 GENIAC)に参画中
Q. ドキュメント書いてますか︖メンテナンスできてますか︖
Q. ドキュメント書いてますか︖メンテナンスできてますか︖ ドキュメント管理についてはどの組織も少なからず苦労しているはず
推しのドキュメント管理ツールと その運⽤について話します💪
🗒 ドキュメント管理ツールは群雄割拠 組織、チームによってツールがバラバラでどれが良いのか悩ましい
✅ 個⼈的ドキュメント管理ツールの要件 1. マークダウンで書ける 2. 検索機能を備えている 3. バージョン(Git)管理できる 4. レビュープロセスを実施しやすい
書きやすさ 👉 参照容易性 👉 メンテナンス性 👉 品質 👉
🦖 選ばれたのは Docusaurus でした 2023/10 にバージョン3がリリース
概要 • Meta によって公開されているオープンソースの静的サイトジェネレーター • 技術ドキュメントの作成に特化しており、マークダウンの記述のみでコンテンツを追加できる 🤔 Docusaurus is 何︖
特徴 • MDX で編集可能 • エンジニアフレンドリーな UI • 検索機能 • バージョン管理機能 • i18n サポート
🙌 こんな感じの良さげな wiki が⼿軽に作れる
以降はチームで実際に運⽤した話 Docusaurus ⾃体ではなくそれを使った運⽤の話
通常の開発と同じようにレビュープロセスを踏み、実装と同じタイミングで ドキュメントも追加する 🧭 運⽤⽅針1 あとでドキュメント追加するタイミングは⼤体来ないので実装と合わせて追加・更新 実際のドキュメント追加のPR
フロー型情報は Confluence や GitHub Issue、ストック型情報は Docusaurus で管理する 全てのドキュメントを Docusaurus 上で管理するのはきつい
👉 ストックしても効果が薄い情報(フロー型情報)は管理しない 🧭 運⽤⽅針2 調査ログ 個別タスクの実装⽅針 MTGの議事録 など 環境構築 リリースの⼿順書 設計資料 アプリ仕様書 など フロー型情報 ストック型情報 賞味期限が短い or コードから辿れれば良いだけの情報 賞味期限が⻑い情報 or 仕様に関する情報
✅ その他メンテナンス上の⼯夫 • ドキュメントの種類別にテンプレートを⽤意する • ドキュメント更新のチェックリストをPRのテンプレに加える • マークアップ系の Linter を使う
• 更新防⽌⽤のワークフローを⽤意する PRのチェックリスト 更新チェック⽤のワークフロー
📝 まとめ • 開発系のドキュメント管理には Docusaurus がおすすめ • Docusaurus を使うことでメンテナンス性が向上 •
他のドキュメントツールと併⽤したり、LinterやCIを活⽤したりすることで⽣産性Up
ご清聴ありがとうございました🙇