Dora Pocket

Appearance

用户指南模板 ​

本模板用于生成用户使用指南，适用于快速上手、操作手册、使用教程等场景。遵循 Layer 1 通用规范 + Layer 2 用户指南规范。

文档结构模板 ​

Frontmatter ​

yaml
---
title: '[功能/模块名称] 使用指南'
description: '[完整的功能说明和适用场景]'
category: 指南
ai_model: Gemini # 推荐使用 Gemini 进行示例生成
---

章节结构 ​

1. 快速开始 ​

目的: 让用户在最短时间内完成安装和运行第一个示例。

内容要求:

  • 安装步骤: 清晰的安装命令和环境要求
  • 基础示例: 一个完整可运行的最小示例
  • 预期结果: 说明示例运行后的预期输出
  • 下一步: 引导用户进一步探索

示例结构:

markdown
## 快速开始

### 安装

\`\`\`bash

# 使用 pnpm 安装

pnpm add @esdora/[package-name]

# 或使用 npm

npm install @esdora/[package-name]
\`\`\`

**环境要求**:

- Node.js >= 18.0.0
- TypeScript >= 5.0.0 (可选)

### 第一个示例

\`\`\`typescript
import { functionName } from '@esdora/[package-name]'

// 基础用法
const result = functionName(input)
console.log(result) // => 预期输出
\`\`\`

**预期结果**: 应该看到 `[描述输出结果]`

### 下一步

- 阅读 [核心概念](#核心概念) 了解工作原理
- 查看 [使用说明](#使用说明) 探索更多功能

2. 核心概念 ​

目的: 解释系统的关键术语、工作原理和设计理念。

内容要求:

  • 术语表: 定义核心术语和概念
  • 工作原理: 用简单语言说明系统如何工作
  • 设计理念: 解释为什么这样设计（可选）
  • 图表辅助: 使用流程图或示意图增强理解

示例结构:

markdown
## 核心概念

### 关键术语

- **[术语1]**: [简明定义和用途说明]
- **[术语2]**: [简明定义和用途说明]

### 工作原理

[用简单语言解释系统的工作流程，必要时使用 Mermaid 流程图]

\`\`\`mermaid
flowchart LR
A[输入] --> B[处理]
B --> C[输出]
\`\`\`

### 设计理念 (可选)

[说明为什么采用这种设计方式，帮助用户理解系统的价值]

3. 使用说明 ​

目的: 提供完整的功能使用指导和配置说明。

内容要求:

  • API 调用: 详细说明各个 API 的使用方法
  • 配置选项: 列出所有配置参数及其作用
  • 使用场景: 针对不同场景提供具体示例
  • 完整可运行: 所有示例必须包含必要的 import 和上下文

示例结构:

markdown
## 使用说明

### 基础用法

\`\`\`typescript
import { functionName } from '@esdora/[package-name]'

// 场景1: [描述使用场景]
const result1 = functionName(input1) // => 输出1

// 场景2: [描述使用场景]
const result2 = functionName(input2) // => 输出2
\`\`\`

### 配置选项

| 参数      | 类型     | 默认值      | 描述       | 必需 |
| --------- | -------- | ----------- | ---------- | ---- |
| `option1` | `string` | `'default'` | [参数说明] | 是   |
| `option2` | `number` | `0`         | [参数说明] | 否   |

**配置示例**:
\`\`\`typescript
const config = {
option1: 'custom-value',
option2: 100
}

const result = functionName(input, config)
\`\`\`

### 高级用法

#### [高级功能1]

[说明和示例代码]

#### [高级功能2]

[说明和示例代码]

4. 常见问题 ​

目的: 提前解答用户可能遇到的问题和困惑。

内容要求:

  • 问题导向: 以问题为标题，直接给出答案
  • 排查指导: 提供常见错误的排查步骤
  • 解决方案: 给出具体可行的解决方法
  • 边界情况: 说明特殊输入或场景的处理

示例结构:

markdown
## 常见问题

### 如何处理 [特定场景]？

[直接给出解决方案和示例代码]

\`\`\`typescript
// 解决方法
const solution = handleSpecialCase(input)
\`\`\`

### 遇到 [错误信息] 怎么办？

**原因**: [说明错误产生的原因]

**解决步骤**:

1. 检查 [检查项1]
2. 确认 [检查项2]
3. 如果问题仍存在，[进一步排查方法]

### 支持哪些输入类型？

[列出支持的输入类型和边界情况处理]

- ✅ 支持: [类型1]、[类型2]
- ❌ 不支持: [类型3] (原因: [说明])
- ⚠️ 注意: [特殊情况说明]

AI 生成提示词 ​

以下提示词适用于使用 Gemini 生成用户指南（推荐模型：gemini-2.5-pro）。

角色定义 ​

你是一位技术写作专家和用户体验设计师，擅长将复杂的技术概念转化为清晰易懂的用户指南，善于从用户视角出发设计文档结构。

任务说明 ​

基于提供的功能说明、API 文档或代码库，生成一份用户友好的使用指南，符合以下规范：

  1. 遵循规范:

    • Layer 1 通用文档规范 (Frontmatter、标题结构、语言、链接格式、代码示例、注意事项)
    • Layer 2 用户指南规范 (步骤化组织、问题导向结构、实用示例要求)
    • 本模板的 4 个章节结构

  2. 内容要求:

    • 快速开始章节: 提供完整的安装步骤和一个最小可运行示例，包含预期结果验证
    • 核心概念章节: 定义关键术语，用简单语言解释工作原理，必要时使用 Mermaid 流程图
    • 使用说明章节: 提供多个使用场景的完整示例，列出所有配置选项和参数说明
    • 常见问题章节: 以问题为标题，提供直接可行的解决方案和排查步骤

  3. 质量检查点:

    • 示例可运行性: 所有代码示例包含必要的 import 语句，可以直接复制运行，输出注释 (// =>) 准确
    • 概念解释清晰度: 术语定义简明易懂，工作原理说明避免过度技术化，使用类比或图表辅助理解
    • 问题覆盖全面性: 常见问题章节覆盖至少 5 个典型用户疑问，包括安装问题、使用错误和边界情况

输入要求 ​

  • 功能说明: 提供功能的目标和核心特性
  • API 文档: 如有现成的 API 参考文档或源码注释
  • 使用场景: 说明典型的使用场景和用户需求

输出格式 ​

  • 格式: Markdown 文件，包含 YAML frontmatter
  • 语言: 简体中文（代码注释可使用英文）
  • 代码块: 使用三反引号 (```) 包裹，标注语言类型
  • 输出注释: 使用 // => 行内注释展示代码执行结果

推荐模型 ​

  • 首选: Gemini (gemini-2.5-pro) - 示例生成能力强，擅长内容组织和用户视角思考
  • 备选: Codex (gpt-5.1-codex) - 当侧重代码示例和脚本生成时使用

使用示例 ​

bash
# 使用 Gemini 生成用户指南
cd docs && gemini -p "
PURPOSE: 为 [功能/模块名称] 创建用户使用指南
TASK:
• 设计 3-5 个常用场景的使用示例
• 组织步骤化的安装和配置流程
• 定义核心术语和工作原理说明
• 提供常见问题的解决方案
MODE: write
CONTEXT: @packages/[module-name]/**/* @README.md | Memory: 用户中心原则，示例驱动的文档哲学，遵循 Dora Pocket 文档风格
EXPECTED: 完整的用户指南，包含 4 个章节、可运行示例和 3 个质量检查点的验证
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-component-ui.txt) | 遵循 L1+L2 用户指南规范，所有示例包含完整上下文 | write=CREATE/MODIFY/DELETE
" --approval-mode yolo

核心指令与规范 ​

  1. 继承规范:

  2. 必需章节:

    • 快速开始 (安装、基础示例、预期结果、下一步)
    • 核心概念 (术语表、工作原理、设计理念)
    • 使用说明 (API 调用、配置选项、使用场景)
    • 常见问题 (问题导向、排查指导、解决方案)

  3. 示例要求:

    • 所有代码示例必须包含 import 语句
    • 使用 // => 行内注释展示输出
    • 示例贴近实际使用场景，完整可运行

  4. 质量检查要点:

    • 示例可运行性: 验证所有代码示例可以直接复制运行
    • 概念解释清晰度: 确保术语定义易懂，工作原理说明避免过度技术化
    • 问题覆盖全面性: 常见问题章节至少包含 5 个典型疑问和解决方案

相关文档 ​

版本历史 ​

  • v1.0 (2025-11-19): 初始版本，定义用户指南的 4 个章节结构和 AI 生成提示词

基于 MIT 许可证发布

版权所有 © 2024-2025 Esdora