文档写作规范
SyncTV 文档按读者任务组织。写文档前先确定读者是谁、读者要完成什么、完成后如何验证。不要把概念解释、操作步骤、字段参考和排障矩阵塞进同一页。
| 类型 | 用途 | 写法 |
|---|---|---|
| Task | 帮读者完成一个具体动作 | 先给前置条件，再给步骤，最后给验证和失败处理 |
| Concept | 解释产品模型或系统边界 | 说明对象、关系、责任边界和下一步，不放完整字段表 |
| Reference | 查字段、命令、指标、错误码 | 保持结构稳定、可搜索，不承担教学 |
| Troubleshooting | 按现象定位问题 | 用“现象、先检查、交给谁/下一步”组织 |
| Runbook | 管理员或运维执行流程 | 明确影响范围、操作顺序、回滚和验证 |
首段直接回答“这页帮你做什么”。不要写泛泛的背景介绍。
推荐：
这页说明如何创建房间、设置加入规则，并用普通成员账号验证房间可以正常进入。避免：
本章节将全面介绍 SyncTV 房间相关能力和复杂边界。- Task 页标题使用动作：
创建和加入房间、添加媒体。 - Concept 页标题使用名词：
播放模型、权限模型。 - Reference 页标题使用对象：
Runtime settings 参考、Metrics Catalog。 - 标题不写“完整指南”“全面说明”“最佳实践”这类空泛词。
优先使用短句和主动表达。能写具体动作时，不写抽象评价。
| 少用 | 改成 |
|---|---|
| 通常应该先确认 | 先检查 |
| 相关页面 | 下一步、参考、继续排查 |
| 语义 | 含义、影响、规则 |
| 边界 | 责任、范围、限制 |
| 生产规则 | 上线前检查、操作规则 |
这些词不是禁用词。配置、安全和架构页可以使用它们，但不能作为固定模板反复出现。
- 链接放在读者需要下一步的位置。
- Task 页结尾使用“下一步”，不要机械堆“相关页面”。
- Reference 页可以保留参考链接，但每个链接要有明确用途。
- 不使用旧路径
deployment/、guides/。 - 不使用脆弱锚点链接指向长页内部标题；优先链接到独立页面。
| 术语 | 中文写法 | 英文写法 |
|---|---|---|
| Provider | Provider 或媒体源 Provider | Provider |
| Realtime | Realtime 或实时连接 | Realtime |
| runtime settings | runtime settings 或运行设置 | runtime settings |
| management gRPC | management gRPC 或管理控制面 | management gRPC |
| proxy slice cache | proxy slice cache | proxy slice cache |
首次出现时解释含义，之后保持同一页面内一致。不要把同一概念在同一页里写成多套名字。
每个中文页面必须有英文镜像，路径在 en/ 下保持一致。英文页面按英文产品文档习惯重写，不逐句直译中文：
- 英文用短句。
- 标题用动词或清晰名词。
- 少用 abstract nouns。
- 中文能保留的产品名，英文仍保留产品名。
提交文档前运行：
cd docsnpm run validate校验会检查内部链接、Starlight 图标、旧路径、旧标题、未完成标记和英文镜像。模板化收尾会作为 warning 输出，逐步清理。