webconsulting-create-documentation

webconsulting — ドキュメントの作成

ソース：https://github.com/dirnbauer/webconsulting-skills

製品ドキュメントを作成するためのエンドツーエンドのワークフローです。ヘルプページ、AI 生成のイラスト、ナレーション付き製品ツアー動画（Remotion + ElevenLabs TTS + Suno AI の音楽）、GitHub README のビジュアルドキュメントを作成します。

前提条件

必須

依存関係	インストール方法	用途
Node.js 20+	プリインストール済み	ランタイム
Remotion	npm install remotion @remotion/cli @remotion/player	動画の合成
qrcode.react	npm install qrcode.react	エンドカードの QR コード
tsx	npm install -D tsx	TypeScript スクリプトの実行

オプション（本番品質向け）

依存関係	インストール方法	用途
ElevenLabs API key	elevenlabs.io	高品質な TTS ナレーション（Jony Ive の声）
ffmpeg	brew install ffmpeg	音声を MP3 に変換（ファイルサイズを縮小）
macOS say + afconvert	macOS に内蔵	フォールバック TTS（Daniel の声、WAV を出力）
Suno API key	api.box	AI 生成のバックグラウンドミュージック

ElevenLabs のセットアップ

1. elevenlabs.io で無料アカウントを作成します
2. サイドバーで Profile + API key に移動します
3. API キーをコピーします
4. .env ファイルに追加します。

ELEVENLABS_API_KEY=your-api-key-here

チーム向けのドキュメントとして、.env.example にも（コメントアウトした状態で）追加します。

# ELEVENLABS_API_KEY=your-elevenlabs-api-key

音声の選択：デフォルトの音声は「Daniel」（onwK4e9ZLuTAKqWW03F9）です。落ち着いたイギリス英語の声です。 elevenlabs.io/voice-library を参照し、より適した音声が見つかった場合は scripts/generate-narration.ts の VOICE_ID を更新してください。

無料プランの制限：月あたり約 10,000 文字です。ナレーションの全文は約 600 文字なので、 無料プランでは月あたり約 16 回再生成できます。

ワークフローの概要

1. Create help page       → React component with collapsible sections
2. Generate illustrations → AI image generation tool (GenerateImage)
3. Build Remotion video   → Animated scenes with narration subtitles
4. Generate TTS audio     → ElevenLabs API or macOS `say` fallback
5. Generate music         → Suno AI background music (optional)
6. Render final video     → npm run remotion:render
7. GitHub README          → Embed screenshots + video in README.md

フェーズ 1：ヘルプページ

src/app/(dashboard)/help/page.tsx にアプリ内ヘルプページを作成します。

構成パターン

// Collapsible section wrapper
function HelpSection({ id, icon, title, description, children, defaultOpen }) {
  const [open, setOpen] = useState(defaultOpen);
  return (
    <Card id={id}>
      <button onClick={() => setOpen(o => !o)}>
        {/* Header with icon, title, description, chevron */}
      </button>
      {open && <CardContent>{children}</CardContent>}
    </Card>
  );
}

// Step-by-step instruction
function Step({ number, title, children }) { /* numbered step */ }

// Pro tip callout
function Tip({ children }) { /* highlighted tip box */ }

// Screenshot placeholder
function Screenshot({ src, alt, caption }) { /* Next/Image with caption */ }

含める主なセクション

1. 目次 — セクションデータからアンカーリンク付きで自動生成します
2. はじめに — 初回利用者向けの案内（デフォルトで開いた状態）
3. 機能セクション — 主要機能ごとに 1 つ（ダッシュボード、クライアント、拡張機能など）
4. 製品動画 — レンダリング済みの MP4 を参照する埋め込み <video> 要素
5. よくある質問／トラブルシューティング — よくある質問

執筆ガイドライン

• 対象読者：技術的な知識が少ないユーザー
• 経験豊富なテクニカルライターのように、明確で親しみやすく、専門用語を避けて書きます
• 各セクションには、スクリーンショット付きの番号付き手順を含めます
• プロ向けのヒントには「ヒント」のコールアウトを使います
• Tailwind v4 の構文を使います（!mt-3 ではなく mt-3!）

フェーズ 2：スクリーンショット／イラスト

スクリーンショットのブラウザー自動化は信頼性に欠ける場合があるため、AI 生成のイラストを使います。

GenerateImage ツールの使用

GenerateImage({
  description: "Modern flat illustration of a monitoring dashboard with
    stat cards showing Total Clients, Extensions, Security Issues.
    Dark theme, clean UI, subtle orange accents.",
  filename: "dashboard.png"
})

生成した画像を public/help/ に配置します。

public/help/
├── dashboard.png
├── clients.png
├── wizard.png
└── product-tour.mp4   (rendered later)

ヘルプページで参照します。

<Screenshot src="/help/dashboard.png" alt="Dashboard overview" caption="The main dashboard" />

フェーズ 3：Remotion 製品動画

ディレクトリ構成

remotion/
├── index.ts          # registerRoot entry point
├── Root.tsx          # Composition definitions
└── ProductTour.tsx   # All scenes + narration script

コンポジションのセットアップ（Root.tsx）

import { Composition } from "remotion";
import { ProductTour } from "./ProductTour";

export const RemotionRoot = () => (
  <Composition
    id="ProductTour"
    component={ProductTour}
    durationInFrames={30 * 45}  // 45 seconds at 30fps
    fps={30}
    width={1920}
    height={1080}
  />
);

シーンのパターン

各シーンは次の構成に従います。

function SceneComponent() {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  return (
    <AbsoluteFill style={{ backgroundColor: DARK_BG, padding: 80 }}>
      <SceneAudio scene="scene-name" />           {/* TTS audio */}
      <FadeInText fontSize={56}>Title</FadeInText> {/* Animated heading */}
      {/* Scene-specific content with spring/interpolate animations */}
      <NarrationSubtitle text={NARRATION_SCRIPT.sceneName} />  {/* Subtitles */}
    </AbsoluteFill>
  );
}

推奨シーン（全 7 シーン、約 75 秒）

長さは動的で、ナレーション音声の長さに応じて決まります（フェーズ 5 を参照）。 動画には、1.5 秒のリードイン（暗転 + 指数関数的な音量ランプ）と、 ソーシャルリンクを表示して黒へフェードする4 秒のエンドカードが含まれます。

#	シーン	約所要時間	内容
—	リードイン	1.5 秒	暗い画面、音楽がフェードイン（指数関数的な t^2.5）
1	イントロ	13 秒	ロゴ + タグライン + ブランドアイデンティティ
2	ダッシュボード	12 秒	スプリングアニメーション付きの統計カード
3	クライアント	12 秒	スライドインする行を使ったクライアント一覧
4	ウィザード	11 秒	段階的にアクティブ化するステップインジケーター
5	セキュリティ	11 秒	順にフェードインする機能グリッド
6	アウトロ	11 秒	ロゴ + CTA + クレジット + ウェブサイト（ブログを強調）
7	エンドカード	7 秒	4 つの QR コード（ウェブサイト、GitHub、YouTube、X）+ 拡大して締めくくり

導入とエンドカード

導入では指数関数的な音量カーブ（Math.pow(t, 2.5)）を使用します。これは、人間の聴覚が対数スケール（ウェーバー・フェヒナーの法則）に従うためです。線形に音量を上げると中盤で「急に」聞こえますが、べき乗カーブなら聴感上なめらかになります。

エンドカードには、ソーシャルメディアやウェブサイトへのリンクを含む4つのQRコードを表示します（順番にスライドして表示）。黒へのフェードアウトはありません。視聴者がスキャンできるよう、QRコードは完全に表示されたままにします。最後の2秒間は、カード全体を大幅に拡大（1.0 → 1.5）し、T3 Monitoring のロゴとともに、自信に満ちた映画のような締めくくりを演出します。「Find us on」の見出しも連動して拡大しますが、拡大するQRコードの列に隠れないよう、上方向（-120px）にも移動します。

QRコードは qrcode.react を使用してインラインでレンダリングします（npm install qrcode.react）。

export const LEAD_IN_FRAMES = Math.round(30 * 1.5); // 45 frames
export const END_CARD_FRAMES = Math.round(30 * 7);   // 210 frames

コンポジションの再生時間を設定するため、これらを Root.tsx の TOTAL_FRAMES に加えます。

エンドカードのリンク

#	プラットフォーム	ハンドル	強調表示
1	ウェブサイト	webconsulting.at	オレンジ色の枠線、説明付きの /blog の案内
2	GitHub	@dirnbauer	—
3	YouTube	@webconsulting-curt	—
4	X	@KDirnbauer	—

ウェブサイトのカードは強調表示します。ハンドルのテキストとQRコードの枠線をオレンジ色にし、その下に /blog のピル型バッジを配置します。ガラス風のコンテナにオレンジ色の枠線と光彩の影を付け、「Tutorials & deep dives」のラベルを表示します。

QRコードのパターン

import { QRCodeSVG } from "qrcode.react";

<QRCodeSVG value="https://webconsulting.at" size={140}
  bgColor="#ffffff" fgColor="#0f172a" level="M" />

各ソーシャルカードには、プラットフォームのアイコンとハンドル、QRコード（白い背景、暗い前景色、角丸のコンテナ）、URLテキスト、任意の強調表示を含めます。

アニメーションツールキット

// Fade + slide up
const opacity = interpolate(frame - delay, [0, fps * 0.6], [0, 1], {
  extrapolateLeft: "clamp", extrapolateRight: "clamp",
});

// Spring bounce for cards
const scale = spring({ fps, frame: frame - i * 8, config: { damping: 80 } });

// Staggered slide-in for list items
const slideX = interpolate(frame - i * 10, [0, fps * 0.5], [100, 0], {
  extrapolateLeft: "clamp", extrapolateRight: "clamp",
});

詳細リファレンス

詳細な例、長いテンプレート、トラブルシューティング用マトリックス、付録、または上記に含まれていないセクションが必要な場合は、完全ガイドをお読みください。限定的なタスクでは、このファイルを読み込まず、スキルが段階的に情報を開示するようにしてください。