docs-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docs sync

文档同步

Goal

目标

Update documentation so it matches the current code and is easy for the target audience to follow.

更新文档，使其与当前代码保持一致，便于目标受众轻松查阅。

Inputs to ask for (if missing)

需索取的输入信息（若缺失）

What changed (feature/bugfix/refactor) and who the docs are for.
Which docs surfaces matter: README,
```
/docs
```
, wiki, runbooks, API spec, changelog, onboarding.
Any required format/voice (company style guide, "keep it short", etc.).

变更内容（功能/漏洞修复/重构）以及文档面向的受众。
涉及的文档载体：README、
```
/docs
```
、wiki、运行手册、API 规范、更新日志、入职指引。
任何要求的格式/文风（公司风格指南、“保持简洁”等要求）。

Workflow (checklist)

工作流（检查清单）

Identify what changed
- Use the diff to locate impacted areas:
  - ```
  git diff --name-only
```
- ```
git diff
```
Inventory docs surfaces in the repo
- Common locations:
```
README.md
```
  ,
```
docs/
```
  ,
```
CONTRIBUTING.md
```
  ,
```
CHANGELOG.md
```
  ,
```
openapi.*
```
  ,
```
schema.graphql
```
  ,
```
adr/
```
  ,
```
runbooks/
```
  .
- For Spring: check for generated OpenAPI/Swagger docs or endpoint annotations.
- For Next/TypeScript: check for docs pages, Storybook, or typed API clients.
- If your repo uses
```
docs/
```
  as the primary doc root, see
```
references/docs-structure.md
```
  for a suggested layout.
Decide what needs updating
- Ensure docs cover:
  - setup and local dev commands
  - required env vars / config keys
  - API contract changes (request/response examples)
  - DB migrations and operational steps
  - behavior changes visible to users
- If the change is an architectural/behavioral decision, add or update an ADR (use
```
references/adr-template.md
```
  ).
Apply edits with minimal churn
- Prefer small, targeted edits over rewrites.
- Add examples that are copy/paste runnable.
- Keep headings stable to avoid breaking deep links.
- Use templates in
```
references/
```
  when helpful.
Verify docs are consistent
- Run the repo's existing doc checks if present (md lint, docs build, site build).
- At minimum: ensure code fences match the actual commands and file paths, and env var names match the code.

确认变更内容
- 使用 diff 定位受影响的区域：
  - ```
  git diff --name-only
```
- ```
git diff
```
清点仓库内的文档载体
- 常见位置：
```
README.md
```
  、
```
docs/
```
  、
```
CONTRIBUTING.md
```
  、
```
CHANGELOG.md
```
  、
```
openapi.*
```
  、
```
schema.graphql
```
  、
```
adr/
```
  、
```
runbooks/
```
  。
- 针对 Spring 项目：检查自动生成的 OpenAPI/Swagger 文档或端点注解。
- 针对 Next/TypeScript 项目：检查文档页面、Storybook 或带类型的 API 客户端。
- 如果你的仓库以
```
docs/
```
  作为主文档根目录，可参考
```
references/docs-structure.md
```
  获取推荐的目录结构。
确定需要更新的内容
- 确保文档覆盖以下内容：
  - 环境搭建和本地开发命令
  - 所需的环境变量/配置键
  - API 契约变更（请求/响应示例）
  - 数据库迁移和运维步骤
  - 用户可见的行为变更
- 如果变更属于架构/行为决策，新增或更新对应 ADR（使用
```
references/adr-template.md
```
  模板）。
以最小变动完成编辑
- 优先做小规模的针对性编辑，而非重写全文。
- 添加可直接复制粘贴运行的示例。
- 保持标题稳定，避免破坏深层链接。
- 必要时使用
```
references/
```
  目录下的模板。
校验文档一致性
- 如果仓库有现成的文档检查流程，运行对应检查（md 校验、文档构建、站点构建）。
- 最低要求：确保代码块中的内容与实际命令、文件路径匹配，环境变量名称与代码一致。

Deliverable

交付物

Provide:

The list of docs files updated and why.
A short "How to verify" section (commands or manual checks).

提供以下内容：

已更新的文档文件列表及更新原因。
简短的“验证方式”章节（命令或手动检查步骤）。