# PR #2523 完整报告

- 仓库：`radixark/miles`
- 标题：docs: delete the FAQ page
- 合并时间：2026-08-15 13:34
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2523

---

## 执行摘要

本 PR 将 `docs/faq.md` 全部删除，并从 `docs.json` 中移除 FAQ 导航标签，同时把 `quick-start.md` 和 `installation.md` 中指向 FAQ 的链接分别改为 GitHub issues 和 Debugging 页面。这是一次纯文档清理，删除了 139 行过时且部分有误的内容，消除了导航中的冗余入口，并避免了把用户引向已失效的 Slack 频道。

## 功能与动机

FAQ 页面最初是为了“回答新用户第一周的问题”而建，但经过一段时间后内容严重过时。reviewer Zhichenzzz 在评论中直言“this FAQ looks like very out of date and not ver constructive suggestions”，建议改成引导用户到 GitHub issue 提交问题。作者先尝试局部修订（如修正不存在的 `--ckpt-step` 建议），但最终认为整页保留意义不大，于是改为整体删除，并同步清理所有入站引用，确保文档站点没有死链。

## 实现拆解

1. **删除页面**：移除 `docs/faq.md`，其中包含 14 个 Accordion 形式的常见问题，覆盖训练乱码、Ray 卡住、OOM、多节点失败、batch size 等。
2. **更新导航配置**：在 `docs/docs.json` 中删除 `FAQ` 标签块（该标签下仅有 `faq` 一页），保证导航结构精简且 JSON 解析合法。
3. **清理入站链接**：
 - `docs/getting-started/installation.md` 中失败处理指引从“调试或 FAQ”改为仅指向 Debugging。
 - `docs/getting-started/quick-start.md` 文末的“常见问题看 FAQ”改为“直接开 GitHub issue”。
4. **验证**：通过 `grep -rn "/faq" docs` 确认无残留引用。

### 以下展示 `docs/docs.json` 中导航配置的清理结果：

```json
{
  "tab": "Resources",
  "pages": ["blog/index", "subscribe"]
}
// 原 FAQ 标签（含 "faq" 页面）已删除，导航结构随之精简

```

`quick-start.md` 中的链接调整：

```markdown
<!-- 变更前：If you hit issues, the [FAQ](/faq) covers the common ones. -->
If you hit issues, feel free to open an issue on [GitHub](https://github.com/radixark/miles/issues).

```

## 评论区精华

- Zhichenzzz 指出 FAQ 过时且没有建设性建议，建议改为链接到 GitHub issue。
- Zhichenzzz 还质疑“do we have Miles channel in sglang slack?”，促使作者不再依赖 Slack 频道。
- 作者对自己的两处局部修订都要求“Drop this change”，体现了快速收敛到删除决策。

## 风险与影响

- **风险**：FAQ 中一些通用建议（如 OOM 调参、日志位置）被删除，用户可能需要通过社区提问；但 Debugging 页面和 GitHub issues 能覆盖大部分求助场景。
- **影响**：仅影响 docs 目录，无代码运行时影响；文档导航更简洁，维护成本降低。

## 关联脉络

该 PR 与近期多个文档清理 PR 一脉相承，如 PR#2487 删除导航条 Contact 按钮、PR#2489 简化 sidebar 分组、PR#2537 更新 quick-start 前置检查。整体方向是持续收敛文档导航、去掉过时内容，并将用户引导到更直接有效的反馈渠道。