Back to Details

documentation-updater

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Updater

文档更新器

Maintain project documentation (README, operational guides, reference docs) as a first-class part of shipping changes. Keep documentation accurate and executable as code evolves.
将项目文档（README、操作指南、参考文档）作为交付变更的核心环节。随着代码迭代，确保文档内容准确且可执行。

When to use

使用场景

Activate this Skill when:
  • A change alters how to run/test locally (development environment setup, containerization, bootstrapping).
  • You add/remove/change environment variables, secrets, or configuration files.
  • You change environment/deployment assumptions used by scripts or tools.
  • You add/modify operational scripts (deployment, data seeding, logging, maintenance tasks).
  • You update integrations with external services or APIs.
  • You modify infrastructure setup or deployment processes.
激活此Skill的场景：
  • 变更修改了本地运行/测试方式（开发环境搭建、容器化、项目初始化）。
  • 新增、移除或修改了环境变量、密钥或配置文件。
  • 修改了脚本或工具所依赖的环境/部署前提条件。
  • 新增或修改了操作脚本（部署、数据初始化、日志、维护任务）。
  • 更新了与外部服务或API的集成。
  • 修改了基础设施的搭建或部署流程。

Principles

原则

  1. Prefer updating existing docs over adding new ones. Add a new doc only when it clearly reduces confusion.
  2. Keep docs executable. Commands must match actual scripts/tools; paths must match the project structure.
  3. Respect environment requirements. When docs tell users to run commands/tests, include the correct environment setup steps (e.g., sourcing environment files, activating virtual environments, loading configuration).
  4. Document "what & why", not internal trivia. Focus on user outcomes and maintenance workflows.
  5. Cross-link instead of duplicating. Use references to maintain a single source of truth.
  1. 优先更新现有文档而非新增文档。仅当新增文档能明确减少混淆时才创建新文档。
  2. 确保文档可执行。命令必须与实际脚本/工具一致；路径必须匹配项目结构。
  3. 遵循环境要求。当文档告知用户运行命令/测试时，需包含正确的环境配置步骤（例如，加载环境文件、激活虚拟环境、加载配置）。
  4. 记录“内容与原因”，而非内部细节。聚焦用户成果和维护流程。
  5. 使用交叉引用而非重复内容。通过引用保持唯一的事实来源。

Workflow

工作流程

1) Determine doc impact from the change

1) 确定变更对文档的影响

Identify what category the change falls into and what docs it likely affects.
确定变更所属的类别及其可能影响的文档。

2) Update the smallest set of docs that restores accuracy

2) 更新最少数量的文档以恢复准确性

  • Update only the relevant sections; avoid broad rewrites.
  • Keep headings and tone consistent with the existing file.
  • Prefer adding links from main documentation to detailed reference docs for deep dives, instead of duplicating instructions.
  • 仅更新相关章节；避免大范围重写。
  • 保持标题和语气与现有文件一致。
  • 优先从主文档添加指向详细参考文档的链接以深入说明，而非重复说明内容。

3) Add "quick verification" steps

3) 添加“快速验证”步骤

When documenting new or changed workflows, include:
  • The exact command(s) to run (use project-standard task runners or scripts).
  • The expected output/behavior at a high level (1–2 bullets).
  • Any common failure mode and how to fix it (1 short subsection max).
在记录新的或变更后的工作流程时，需包含：
  • 要运行的准确命令（使用项目标准的任务运行器或脚本）。
  • 高层面的预期输出/行为（1-2个要点）。
  • 常见的失败模式及修复方法（最多1个简短小节）。

4) Check for drift and broken references

4) 检查偏差和无效引用

  • Confirm referenced scripts/commands exist in the project.
  • Confirm file paths and directory references exist in the repository.
  • Verify external links are still valid and accessible.
  • 确认引用的脚本/命令在项目中存在。
  • 确认文件路径和目录引用在仓库中存在。
  • 验证外部链接仍然有效且可访问。