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
240
Docusaurus を使った開発ドキュメントの作成と運用
2024/03/29 第14回LTラジオ
yudai yamamoto
March 29, 2024
Tweet
Share
More Decks by yudai yamamoto
See All by yudai yamamoto
2024年における生成AIエンジニアとは何者か
yyo616
9
3.1k
大規模言語データの前処理とLLM-as-a-Judge の活用
yyo616
4
1k
Playwrightでテストを楽に実装したい
yyo616
0
45
Featured
See All Featured
Code Reviewing Like a Champion
maltzj
518
39k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
42
2k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
226
52k
Side Projects
sachag
451
42k
Build your cross-platform service in a week with App Engine
jlugia
228
18k
A Philosophy of Restraint
colly
202
16k
The Art of Programming - Codeland 2020
erikaheidi
48
13k
Optimizing for Happiness
mojombo
375
69k
Stop Working from a Prison Cell
hatefulcrawdad
266
20k
Product Roadmaps are Hard
iamctodd
PRO
48
10k
Adopting Sorbet at Scale
ufuk
72
8.9k
Why You Should Never Use an ORM
jnunemaker
PRO
53
8.9k
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
ご清聴ありがとうございました🙇