enhance-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Enhance Docs

优化文档

Overview

概述

Improve documentation so it is up to date, coherent, and centered on users' jobs-to-be-done. Favor less content with higher clarity.

改进文档，使其保持最新、连贯，并以用户的jobs-to-be-done为核心。优先选择内容更精简、清晰度更高的文档。

Inputs (ask if missing, max 5)

输入信息（若缺失需询问，最多5项）

Docs scope (which files or sections)
Primary audiences and their jobs-to-be-done
Source of truth for product behavior (code, APIs, changelog)
Recent changes or upcoming releases
Constraints (tone, length, compliance, deadlines)

文档范围（涉及哪些文件或章节）
主要受众及其jobs-to-be-done
产品行为的真实依据（代码、API、更新日志）
近期变更或即将发布的版本
约束条件（语气、篇幅、合规要求、截止日期）

Principles

原则

Less is more: reduce noise, keep only what helps users act.
Low cognitive load: short paragraphs, clear headings, predictable structure.
High signal: prioritize steps, outcomes, and decision points.
JTBD-first: structure around what users are trying to accomplish.

少即是多：减少冗余信息，仅保留对用户行动有帮助的内容。
低认知负荷：使用短段落、清晰标题、可预测的结构。
高信息价值：优先呈现步骤、结果和决策节点。
JTBD优先：围绕用户试图完成的目标构建文档结构。

Workflow

工作流程

Map jobs-to-be-done
- List top 3-5 user jobs and the docs that should enable each.
Check freshness and accuracy
- Compare docs against current behavior, APIs, and recent changes.
Simplify and restructure
- Remove redundancy, collapse long lists, and apply progressive disclosure.
Improve coherence
- Align terminology, fix contradictions, and add consistent cross-links.
Clarify with examples
- Add minimal examples only where they unblock action.
Deliver ranked improvements
- Prioritize changes by impact on user success and confusion reduction.

梳理jobs-to-be-done
- 列出前3-5项用户核心工作，以及应支持这些工作的对应文档。
检查新鲜度与准确性
- 将文档与当前产品行为、API及近期变更进行比对。
简化与重组结构
- 移除冗余内容，合并冗长列表，采用渐进式披露方式。
提升连贯性
- 统一术语，修正矛盾内容，添加一致的交叉链接。
通过示例明确说明
- 仅在能为用户扫清行动障碍的情况下添加必要示例。
交付分级优化方案
- 根据对用户成功的影响程度及减少困惑的效果，对变更内容进行优先级排序。

Output Format

输出格式

undefined

undefined

Documentation Enhancement

文档优化方案

Context Summary

背景摘要

[1-3 sentences]

JTBD Map

JTBD映射

Job: ... -> Docs: ... -> Success criteria: ...

工作：... -> 文档：... -> 成功标准：...

Issues (ranked)

问题列表（按优先级排序）

[Issue] — impact: high, evidence: ...

[问题描述] — 影响程度：高，依据：...

Proposed Changes (ranked)

建议变更（按优先级排序）

[Change] — rationale: ...

[变更内容] — 理由：...

Quick Wins

快速优化项

Open Questions

待解决问题

undefined

undefined

Quick Reference

快速参考

Trim before adding.
Structure by jobs and outcomes, not features.
Keep headings short and action-oriented.

先精简，再新增内容。
按工作目标和结果构建结构，而非功能。
标题应简短且以行动为导向。

Common Mistakes

常见误区

Adding more text instead of removing noise
Mixing audiences in the same section
Describing features without user tasks
Missing cross-links or inconsistent terminology

增加更多文本而非移除冗余信息
在同一章节混合不同受众的内容
仅描述功能而不关联用户任务
缺失交叉链接或术语不一致