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
280
コンテンツモデレーション入門の入門
yyo616
2
150
2024年における生成AIエンジニアとは何者か
yyo616
11
3.7k
大規模言語データの前処理とLLM-as-a-Judge の活用
yyo616
4
1.4k
Playwrightでテストを楽に実装したい
yyo616
0
62
Featured
See All Featured
Fontdeck: Realign not Redesign
paulrobertlloyd
82
5.4k
The Pragmatic Product Professional
lauravandoore
32
6.4k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
251
21k
Building Better People: How to give real-time feedback that sticks.
wjessup
366
19k
Done Done
chrislema
182
16k
Templates, Plugins, & Blocks: Oh My! Creating the theme that thinks of everything
marktimemedia
29
2.2k
Raft: Consensus for Rubyists
vanstee
137
6.8k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
3
320
Imperfection Machines: The Place of Print at Facebook
scottboms
267
13k
BBQ
matthewcrist
86
9.5k
Large-scale JavaScript Application Architecture
addyosmani
510
110k
Dealing with People You Can't Stand - Big Design 2015
cassininazir
366
25k
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
ご清聴ありがとうございました🙇