Back to Details

docs-update

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Bot

文档机器人

Automatically review code changes and update user-facing documentation to keep it synchronized with the codebase. Works across documentation platforms (Mintlify, Docusaurus, GitBook, Fumadocs, etc.) and supports both monorepo and multi-repo setups.
自动审核代码变更并更新面向用户的文档，确保其与代码库保持同步。支持多种文档平台（Mintlify、Docusaurus、GitBook、Fumadocs等），同时兼容单仓（monorepo）和多仓（multi-repo）架构。

Workflow

工作流程

1. Identify Significant Code Changes

1. 识别重要代码变更

Determine which commits need documentation updates:
  • Find the default branch
  • Get recent commits (default: last 24 hours, or accept user-specified timeframe)
  • Examine each commit's changes to understand what was modified
Filter for significant changes:
  • New features or capabilities
  • API changes (new endpoints, parameters, return values)
  • Breaking changes
  • New configuration options
  • New CLI commands or flags
  • Changes to user-facing behavior
Skip documentation for:
  • Internal refactoring
  • Test-only changes
  • Minor bug fixes
  • Typo corrections in code
  • Performance optimizations without user impact
Be conservative: quality over quantity. When in doubt about significance, skip the update.
判断哪些提交需要更新文档：
  • 找到默认分支
  • 获取近期提交记录（默认：过去24小时，也可接受用户指定的时间范围）
  • 检查每个提交的变更内容，明确修改点
筛选重要变更：
  • 新增功能或能力
  • API变更（新增接口、参数、返回值）
  • 破坏性变更
  • 新增配置选项
  • 新增CLI命令或参数
  • 用户可见的行为变更
无需更新文档的情况：
  • 内部重构
  • 仅测试代码的变更
  • 小bug修复
  • 代码中的拼写错误修正
  • 不影响用户的性能优化
保持谨慎：质量优先于数量。若不确定变更是否重要，可跳过更新。

2. Analyze Documentation Context

2. 分析文档上下文

Locate documentation:
  • Check for documentation directory in current repo (monorepo pattern)
  • Look for separate documentation repository in environment
Identify documentation platform: Determine the platform by examining configuration files and directory structure (e.g., Mintlify, Docusaurus, GitBook, Fumadocs, or generic markdown).
Understand documentation style: Read several existing documentation files to identify tone, voice, structure, code example patterns, terminology, and formatting conventions. Check for style guides or contribution documentation.
定位文档位置：
  • 检查当前仓库中的文档目录（单仓架构模式）
  • 查找环境中的独立文档仓库
识别文档平台： 通过检查配置文件和目录结构确定使用的平台（例如Mintlify、Docusaurus、GitBook、Fumadocs或通用Markdown）。
了解文档风格： 阅读若干现有文档文件，确定语气、行文方式、结构、代码示例格式、术语和排版规范。同时查看是否有风格指南或贡献文档。

3. Determine Documentation Updates

3. 确定文档更新内容

Map code changes to documentation needs (new content, modifications, or additions to existing content).
Guidelines:
  • Prioritize user-facing changes over implementation details
  • Match existing documentation verbosity (some docs are comprehensive, others minimal)
  • Preserve existing accurate content—be strictly additive when possible
  • Keep content focused and avoid generic advice
将代码变更映射到文档需求（新增内容、修改现有内容或补充内容）。
指导原则：
  • 优先处理用户可见的变更，而非实现细节
  • 匹配现有文档的详细程度（部分文档全面，部分文档简洁）
  • 保留现有准确内容——尽可能仅做增量更新
  • 内容聚焦，避免通用建议

4. Generate Documentation Changes

4. 生成文档变更

Match existing style:
  • Use the same tone, voice, and formality level identified in step 2
  • Follow the same heading structure and hierarchy
  • Use consistent terminology
  • Match code block formatting (language tags, highlighting)
  • Follow platform conventions (frontmatter, special syntax, custom components)
匹配现有风格：
  • 使用步骤2中确定的相同语气、行文方式和正式程度
  • 遵循相同的标题结构和层级
  • 使用一致的术语
  • 匹配代码块格式（语言标签、高亮样式）
  • 遵循平台约定（前置元数据、特殊语法、自定义组件）

5. Execute or Report

5. 执行或报告

Testing mode (when user asks to "see what would change"):
Output a text summary describing:
  • What changes were detected in commits
  • Which documentation files would be modified
  • What content would be added or changed
  • Rationale for why these updates are needed
Execution mode (when running as automation):
  1. Create a descriptive branch name (e.g., 
    docs/auto-update-YYYYMMDD
    )
  2. Make documentation changes to appropriate files
  3. Commit with descriptive message listing the changes
    • Include co-author line: 
      Co-Authored-By: Warp <agent@warp.dev>
  4. Push branch and create PR with description linking to relevant commits:
    • List which code changes triggered which documentation updates
    • Include commit references or URLs from source repository
    • Request review for accuracy and completeness
测试模式（当用户要求“查看会有哪些变更”时）：
输出文本摘要，内容包括：
  • 提交记录中检测到的变更
  • 哪些文档文件会被修改
  • 将新增或修改的内容
  • 需要进行这些更新的原因
执行模式（作为自动化任务运行时）：
  1. 创建描述性分支名称（例如：
    docs/auto-update-YYYYMMDD
    ）
  2. 对相应文件进行文档变更
  3. 提交时使用描述性消息列出变更内容
    • 包含合著者行：
      Co-Authored-By: Warp <agent@warp.dev>
  4. 推送分支并创建PR，描述中关联相关提交记录：
    • 列出哪些代码变更触发了哪些文档更新
    • 包含源仓库的提交引用或URL
    • 请求审核内容的准确性和完整性

Multi-Repository Setup

多仓库架构

When source code and documentation are in separate repositories, identify changes in the source repo, then switch to the docs repo and follow the workflow above. Reference source commits in the PR description.
当源代码和文档位于不同仓库时，先识别源仓库中的变更，再切换到文档仓库并遵循上述工作流程。在PR描述中引用源仓库的提交记录。

Edge Cases

边缘情况

  • If no significant changes found, report that no documentation updates are needed
  • If documentation platform is unclear, default to standard markdown syntax
  • If conflicting with existing content, preserve existing information and note conflicts for human review
  • 若未发现重要变更，报告无需更新文档
  • 若文档平台不明确，默认使用标准Markdown语法
  • 若与现有内容冲突，保留现有信息并记录冲突，供人工审核

Key Principles

核心原则

  • Conservative: Better to skip than clutter documentation
  • Consistent: Match existing style, tone, and structure exactly
  • Contextual: Consider the full documentation landscape, not just individual files
  • Clear: Explain significance of changes and rationale for updates
  • Practical: Focus on helping users accomplish tasks, not describing implementation
  • 谨慎性：宁可不更新，也不要让文档变得杂乱
  • 一致性：完全匹配现有风格、语气和结构
  • 上下文感知：考虑整体文档体系，而非仅单个文件
  • 清晰性：解释变更的重要性和更新的原因
  • 实用性：聚焦于帮助用户完成任务，而非描述实现细节