faq-tutorial-guidelines.md

FAQ / 教程贡献规范

目标：让任何人都可以提交可复用、可检索、可维护的经验内容，避免口口相传丢失。

适用范围

• FAQ（常见问题与报错处理）
• 使用教程（从 0 到 1、进阶技巧、集成示例）
• 运维经验（排障、监控、升级、回滚）

维护元数据（必填）

所有 FAQ / 教程内容都应在标题下方补一段维护元数据：

> owner: @github-id / team
> audience: 新手 / 运维 / 集成开发者
> last verified: YYYY-MM-DD
> obsolete: false

• owner：后续负责校对、修订、答疑的人或团队。
• audience：目标读者，避免把新手教程写成排障手册，或把运维经验写成泛泛介绍。
• last verified：最近一次按文档步骤、截图或行为重新核对的日期。
• obsolete：默认写 false；如果内容已失效，改为 true，并在正文开头补替代方案、迁移路径或删除计划。

FAQ 模板

复制以下结构提交：

## 问题标题（简短、可搜索）

> owner: @github-id / team
> audience: 新手 / 运维 / 集成开发者
> last verified: YYYY-MM-DD
> obsolete: false

### 现象
- 具体报错信息：
- 出现场景：

### 根因
- 触发原因 1
- 触发原因 2

### 解决步骤
1. 步骤一
2. 步骤二
3. 验证结果

### 预防建议
- 建议一
- 建议二

教程模板

复制以下结构提交：

# 教程标题

> owner: @github-id / team
> audience: 新手 / 运维 / 集成开发者
> last verified: YYYY-MM-DD
> obsolete: false

## 适用人群
- 新手 / 运维 / 集成开发者

## 前置条件
- 条件一
- 条件二

## 操作步骤
1. ...
2. ...
3. ...

## 验证方式
- 成功标准 1
- 成功标准 2

## 常见坑位
- 坑位 1 与规避方式
- 坑位 2 与规避方式

命名与归档建议

• FAQ 统一追加到 /docs/faq.md
• 教程建议新增 docs/community/tutorial-<topic>.md
• 文件名使用小写英文与 -，例如：tutorial-openwebui.md

提交要求

• 标题可检索：包含关键词（平台名、报错码、功能名）
• 步骤可复现：避免 试一下、差不多 这类描述
• 版本要明确：注明适用版本、部署方式
• 结果可验证：给出成功判定标准
• 元数据完整：owner / audience / last verified / obsolete 四项缺一不可

维护原则

• 过时内容要标记 已失效 并给替代方案
• 同类问题合并，避免 FAQ 膨胀重复
• 优先给最短修复路径，再补原理解释
• 正文有实质更新时，同步刷新 last verified
• 负责人变更时，及时更新 owner，不要留下无人维护的教程