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
520
Docusaurus を使った開発ドキュメントの作成と運用
2024/03/29 第14回LTラジオ
yudai yamamoto
March 29, 2024
Tweet
Share
More Decks by yudai yamamoto
See All by yudai yamamoto
AIコーディングネイティブ世代のバイブコーディングに対する雑感
yyo616
0
410
安全性を高めるAzure AI Content Safety について
yyo616
1
370
コンテンツモデレーション入門の入門
yyo616
2
170
2024年における生成AIエンジニアとは何者か
yyo616
11
4.1k
大規模言語データの前処理とLLM-as-a-Judge の活用
yyo616
4
1.7k
Playwrightでテストを楽に実装したい
yyo616
0
80
Featured
See All Featured
For a Future-Friendly Web
brad_frost
179
9.9k
Creating an realtime collaboration tool: Agile Flush - .NET Oxford
marcduiker
31
2.2k
Keith and Marios Guide to Fast Websites
keithpitt
411
22k
Optimizing for Happiness
mojombo
379
70k
Performance Is Good for Brains [We Love Speed 2024]
tammyeverts
10
1k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
251
21k
Connecting the Dots Between Site Speed, User Experience & Your Business [WebExpo 2025]
tammyeverts
8
470
Mobile First: as difficult as doing things right
swwweet
223
9.9k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
194
16k
Docker and Python
trallard
45
3.5k
KATA
mclloyd
32
14k
BBQ
matthewcrist
89
9.8k
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
ご清聴ありがとうございました🙇