Fowel

Fowel 是什么？

Fowel 是一款 GitHub App，用于审查拉取请求中的文档变更。它会自动发布行内评论和总结审查，帮助在变更合并前捕获文档问题——如不正确或过时的信息、缺少上下文、不清晰的表述以及损坏的示例。

Fowel 的核心目的是在代码审查旁添加自动化文档质量检查。它专注于文档文件（包括 Markdown 和 MDX），并从多个质量维度评估，以便开发者和审查者能在工作流程早期解决问题。

主要功能

• 针对每个 PR 的文档审查 GitHub App：Fowel 安装到 GitHub 仓库中，当拉取请求包含文档变更时自动运行审查。
• 自动检测文档文件：当 PR 中修改 Markdown、MDX 和其他文档文件类型时，它会自动检测，审查者无需手动选择检查内容。
• 行内评论 + 总结审查：Fowel 在拉取请求中发布详细的行内反馈和整体审查，确保问题在审查过程中可见。
• 多维度文档审计：检查内容准确性、开发者旅程/入职流程、结构与信息架构、代码示例（包括可运行性和错误处理）、清晰度与风格，以及完整性。
• 支持自动和手动审查：产品同时提供自动化审查运行和手动触发审查功能。

如何使用 Fowel

1. 安装 GitHub App：使用一键安装流程将 Fowel 添加到仓库。网站说明无需配置文件、CI 变更或设置脚本。
2. 打开包含文档变更的拉取请求：将文档更新推送到分支并打开 PR，Fowel 会自动检测文档文件。
3. 在 PR 中查看 Fowel 的反馈：审查 Fowel 发布的行内评论和总结。处理问题（例如过时声明、缺少错误文档或损坏的代码示例），然后根据需要更新 PR。

使用场景

• 合并前捕获过时流程：团队更新 API 文档或指南时，Fowel 可标记代码审查可能遗漏的矛盾和不正确流程。
• 改善“首次成功时间”入职流程：Fowel 评估文档的开发者旅程方面，确保用户不会因缺少设置上下文而中途放弃，从而顺利完成首次 API 调用。
• 验证参考文档质量：针对端点和 API 参考页面，Fowel 检查导航、结构、命名、交叉链接以及文档完整性是否支持开发者查找具体细节。
• 检测损坏或误导性代码示例：当示例过时或缺少必要错误处理时，Fowel 验证可运行性和语法正确性，避免开发者复制/粘贴失败片段。
• 减少因缺少错误/上下文文档导致的支持负担：针对涉及参数、认证说明或错误响应的文档变更，Fowel 关注信息是否存在且足够清晰，以防止“猜测”和重复提问。

常见问题

Fowel 只审查 Markdown 文件吗？
不是。页面说明它会自动检测拉取请求中包含的 Markdown、MDX 和其他文档文件。

结果显示在哪里？
Fowel 在拉取请求中发布行内评论和总结审查。

审查只能自动触发还是支持手动？
两者均支持：产品包括自动审查和手动触发。

Fowel 检查文档哪些方面？
它从多个质量维度进行文档审计，包括内容准确性、开发者旅程、结构与信息架构、代码示例、清晰度与风格，以及完整性。

Fowel 能取代代码审查吗？
网站将 Fowel 定位为拉取请求工作流程中的额外文档质量检查；它补充代码审查，专注于代码审查者可能未标记的文档问题。

替代方案

• 内部文档审查流程（检查清单或同行评审）：团队可依赖人工审查者使用质量检查清单。与 Fowel 相比，此方式自动化程度较低，通常问题发现较晚。
• 静态文档 linting/linters：文档 lint 工具可强制执行格式或基本正确性规则。但它们通常无法提供 Fowel 所述的多维度文档审计和上下文内联审查。
• 内置验证的 API 文档平台：帮助生成 API 文档的工具可减少某些来源的文档漂移，但可能无法像 Fowel 那样审查散文质量、入职流程、结构和示例可运行性。
• 通用拉取请求审查自动化：广泛的 CI 或 PR 自动化可标记构建和测试故障，但并非专为文档准确性、清晰度和完整性量身定制。