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
530
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
530
安全性を高めるAzure AI Content Safety について
yyo616
1
380
コンテンツモデレーション入門の入門
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
Visualization
eitanlees
147
16k
Automating Front-end Workflow
addyosmani
1370
200k
KATA
mclloyd
32
14k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
194
16k
RailsConf 2023
tenderlove
30
1.2k
Fashionably flexible responsive web design (full day workshop)
malarkey
407
66k
Code Review Best Practice
trishagee
70
19k
Building a Scalable Design System with Sketch
lauravandoore
462
33k
XXLCSS - How to scale CSS and keep your sanity
sugarenia
248
1.3M
Optimizing for Happiness
mojombo
379
70k
The Pragmatic Product Professional
lauravandoore
36
6.8k
StorybookのUI Testing Handbookを読んだ
zakiyama
30
6.1k
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
ご清聴ありがとうございました🙇