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	片尾卡中的二维码
tsx	npm install -D tsx	运行 TypeScript 脚本

可选项（用于生产级品质）

依赖项	安装	用途
ElevenLabs API 密钥	elevenlabs.io	高级 TTS 旁白（Jony Ive 音色）
ffmpeg	brew install ffmpeg	将音频转换为 MP3（文件更小）
macOS say + afconvert	macOS 内置	备用 TTS（Daniel 音色，输出 WAV）
Suno API 密钥	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. 功能章节 — 每项主要功能对应一个章节（仪表盘、客户、扩展等）
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.5s	暗屏，音乐淡入（指数曲线 t^2.5）
1	介绍	13s	Logo + 标语 + 品牌形象
2	仪表盘	12s	带弹簧动画的统计卡片
3	客户	12s	带滑入行的客户列表
4	向导	11s	逐步激活的步骤指示器
5	安全	11s	依次淡入的功能网格
6	结尾	11s	Logo + CTA + 致谢 + 网站（重点展示博客）
7	片尾卡	7s	4 个二维码（网站、GitHub、YouTube、X）+ 放大收尾

开场和结束卡片

开场使用指数音量曲线（Math.pow(t, 2.5)），因为人类听觉遵循对数刻度（韦伯-费希纳定律）。线性渐变在中途听起来会很“突然”；幂函数曲线在感知上更加平滑。

结束卡片展示 4 个带有社交媒体／网站链接的二维码（依次向上滑入）。 不淡出至黑屏——二维码会保持完全可见，以便观众扫描。 在最后 2 秒，整个卡片会大幅放大（1.0 → 1.5），并显示 T3 Monitoring 徽标，营造自信且富有电影感的收尾。 “Find us on”标题会同步放大，同时也会向上移动（-120px），以免被不断扩大的二维码行遮挡。

二维码使用 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	—

网站卡片会特别突出：橙色用户名文字、橙色二维码边框，以及下方的 /blog 胶囊徽标——采用玻璃风格容器，带有橙色边框、辉光阴影和“教程与深入解读”标签。

二维码样式

import { QRCodeSVG } from "qrcode.react";

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

每张社交媒体卡片都显示：平台图标 + 用户名、二维码（白色背景、深色前景、圆角容器）、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",
});

详细参考

当任务需要详细示例、长模板、故障排查矩阵、附录或上文未涵盖的章节时，请阅读完整指南。对于范围较窄的任务，请勿加载此文件，以便技能遵循渐进式披露原则。