概要

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変更→ビルド→コミットで常に最新のヘルプセンターを維持
  • 手動キャプチャや画像編集の手間が完全になくなった

• 「なぜもっと早くやらなかったのか」と感じる便利さ

  • 開発者・運用者双方の心理的負担を大幅軽減
  • ユーザーにとっても常に正確なドキュメント提供が可能