概要
Jelly のヘルプセンターでは、 自動スクリーンショット取得システム を構築。 UI変更時も 一括自動更新 で、古い画像問題を解消。 Markdown 内の特殊コメントで、柔軟にスクリーンショット指定。 Rakeタスク による自動化で、運用負担を大幅削減。 コードとドキュメントの同期 が容易になり、運用効率化を実現。
Jellyのヘルプセンター自動スクリーンショットシステム
-
ヘルプセンターやドキュメントサイト運用 における最大の悩み：スクリーンショットの陳腐化問題
- UI変更のたびに、手動で画像を撮り直し・加工・差し替えが必要
- 古い画像が残ることで、ユーザー体験や信頼性が低下
-
Jelly独自の解決策 ：スクリーンショット自動取得＆自動更新システムの開発
- ビルド時に 全スクリーンショットを最新状態で自動生成
- UI変更後も コマンド一発 で全画像を更新可能
-
Markdownベースのドキュメント管理
- 記事は Markdown で記述、Redcarpet経由でHTML変換し、RailsアプリでERBとしてレンダリング
- Markdown内に 特殊なHTMLコメント （例：
<!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->）を埋め込むことで、取得対象や方法を細かく指定
-
スクリーンショット取得の仕組み
- Rakeタスク が Capybara ＋ Cuprite でヘッドレスChromeを起動
- Markdownをパースし、SCREENSHOTコメントを抽出・チームごとにグルーピング
- URL遷移・ログイン・DOM要素取得・キャプチャを自動化
-
対応モードとオプション
- element ：CSSセレクタ指定のDOM要素のみをキャプチャ
- full_page ：ページ全体を指定範囲でキャプチャ
- viewport ：ブラウザウィンドウに見えている範囲のみキャプチャ
- click ：ボタン等を自動クリックし、動的UIの状態も取得可能
- wait ：アニメーション等の待機も指定可能
- crop ：キャプチャ後のトリミングも自動対応
- torn ：CSSでちぎり紙風のエフェクトを自動適用
- hide ：不要な要素（例：開発ツールバーやCookieバナー）を一時的に非表示
-
運用フローの効率化
rails manual:buildコマンド一発で全プロセス自動化- UI変更時も 画像の取り忘れや差し替え漏れゼロ
- Markdownファイルは
public/manual/にセクションごとで管理、ビルド後はapp/views/help/にERBとして整理 - パンくずリストやセクションナビゲーションも自動生成
-
コードとドキュメントの同期性向上
- 機能開発と同時にドキュメント更新 が可能
- 同じPRやコミット でコードと説明を一元管理
導入して感じた効果と学び
-
最初は「手間の割にメリットが少ない」と感じて後回しにしていた
- 実装には 細かい例外処理 （スクロール、ポップオーバー、不要部分の切り抜き等）が多く、想定以上に工数がかかった
-
導入後は運用効率が劇的に向上
- 摩擦がほぼゼロ になり、ドキュメント更新頻度が大幅増
- UI変更→ビルド→コミット で常に最新のヘルプセンターを維持
- 手動キャプチャや画像編集の手間が完全になくなった
-
「なぜもっと早くやらなかったのか」と感じる便利さ
- 開発者・運用者双方の心理的負担を大幅軽減
- ユーザーにとっても常に正確なドキュメント提供が可能