cloud
69 lines
1.6 KiB
Markdown
69 lines
1.6 KiB
Markdown
---
|
|
name: edge-doc-coauthoring
|
|
description: edge_collector 文档协作规范。用于编写或更新方案设计、部署说明、协议文档、事故分析、本地模型方案、用户手册等 docs 文档时，帮助确定读者、落点、结构、验证依据和后续实施清单。
|
|
---
|
|
|
|
# edge_collector 文档协作
|
|
|
|
## 文档落点
|
|
|
|
- 协议实现：`collector/docs/protocols/`
|
|
- 协议清单：`collector/docs/协议支持清单.md`
|
|
- 边缘/云端通用方案：`docs/`
|
|
- 鲁班猫设备问题：`docs/鲁班猫1/`、`docs/鲁班猫3/`
|
|
- 本地模型方案：`docs/本地模型/`
|
|
- 部署/同步/运维：`docs/` 或 `docs/ops/`
|
|
|
|
## 写作流程
|
|
|
|
1. 明确读者：开发、运维、现场用户、管理后台用户。
|
|
2. 明确目标：评估、实施、排障、交付说明、用户操作。
|
|
3. 收集依据：代码路径、配置文件、脚本、远程验证、官方文档链接。
|
|
4. 写清边界：第一版做什么、不做什么、风险和前置条件。
|
|
5. 给出可执行步骤：命令、目录、配置示例、验证方法。
|
|
|
|
## 推荐结构
|
|
|
|
技术方案：
|
|
|
|
```text
|
|
背景与目标
|
|
当前现状
|
|
方案设计
|
|
目录/配置/API
|
|
实施步骤
|
|
验证计划
|
|
风险与对策
|
|
参考资料
|
|
```
|
|
|
|
事故分析：
|
|
|
|
```text
|
|
问题现象
|
|
影响范围
|
|
现场证据
|
|
根因分析
|
|
修复方案
|
|
验证结果
|
|
预防措施
|
|
```
|
|
|
|
用户说明：
|
|
|
|
```text
|
|
功能用途
|
|
使用步骤
|
|
参数解释
|
|
常见问题
|
|
注意事项
|
|
```
|
|
|
|
## 约束
|
|
|
|
- 给用户看的协议介绍不透露内部技术细节。
|
|
- 技术方案可写实现细节，但要标注假设和验证状态。
|
|
- 引用外部信息时提供链接。
|
|
- 不把未经验证的能力写成已完成。
|
|
|