工程师上手指南

本指南帮助技术人员快速上手文档站的协作流程。

我能做什么

• 编写和维护产品技术文档（Markdown 格式）
• 提交文档修改（通过 Git Pull Request）
• 经过审核后，文档自动发布到 docs.videowell.work

我不能做什么

• ❌ 直接修改线上文档（需审核）
• ❌ 访问门户网站后台
• ❌ 访问产品数据库或客户数据
• ❌ SSH 登录服务器

第一步：准备工作

安装 Git

Windows / macOS：推荐安装 GitHub Desktop（图形界面，无需命令行）。

或安装 Git 命令行：git-scm.com

安装编辑器

推荐 VS Code（免费）：

1. 下载 VS Code
2. 安装后，左侧「扩展」搜索安装 Markdown Preview Enhanced（实时预览 Markdown）

第二步：克隆文档仓库

GitHub Desktop（推荐新手）

1. 打开 GitHub Desktop
2. File → Clone Repository
3. 输入文档仓库地址（联系团队管理员获取）
4. 选择本地保存路径 → Clone

VS Code

1. 打开 VS Code
2. 左侧 Source Control 图标 → Clone Repository
3. 输入仓库地址 → 选择本地路径

第三步：编写文档

文档存放位置

docs/
├── public/products/    ← 公开文档（搜索引擎可见）
│   └── em2860/        ← 按产品型号分目录
│       ├── index.md
│       ├── quick-start.md
│       └── faq.md
└── private/           ← 私密文档（需登录查看）

新建文档

1. 在对应产品目录下新建 .md 文件
2. 文件名用英文 + 连字符：driver-install.md、sdk-guide.md
3. 在关联的 index.md 中添加链接

Markdown 语法速查

# 一级标题
## 二级标题
### 三级标题

**粗体** *斜体*

- 无序列表
1. 有序列表

[链接文字](URL)

![图片描述](图片URL)

`行内代码`

​```bash
代码块
​```

> 引用块

| 表格 | 标题 |
|------|------|
| 数据 | 数据 |

::: tip 提示
提示信息块
:::

::: warning 注意
警告信息块
:::

第四步：提交审核

GitHub Desktop

1. 左侧 Changes 标签 → 勾选要提交的文件
2. Summary 填写简明改动说明（如「新增 EM2860 SDK 指南」）
3. 点击 Commit to main
4. 点击 Push origin
5. 点击 Create Pull Request → 填写说明 → 提交

VS Code

1. 左侧 Source Control → Stage Changes（"+"按钮）
2. Message 输入改动说明 → 点击 ✓ Commit
3. 点击 Sync Changes 推送到远程
4. 在仓库网页上点 New Pull Request

第五步：等待审核

1. 提交 PR 后，审核人会收到通知
2. 审核人检查内容后：
   • 批准 → 合并到主分支 → 自动部署上线
   • 要求修改 → 你会收到修改意见，改后重新推送即可

文档编写规范

标题层级

• # 只用一次（文档标题）
• ## 用于大章节
• ### 用于小节

内容的正确示例

# EM2860 驱动安装

## Linux 驱动

### 内核原生支持

EM2860 在 Linux 内核中已有 V4L2 驱动支持，通常即插即用。

代码示例：
​```bash
lsmod | grep em28xx
​```

## Windows 驱动

...

注意事项

• 参数一律对照知识库（CC-1/docs/knowledge-base/），不自行猜测
• 不确定的参数标注：⚠️ 待确认：XXX 参数需核查规格书
• 每个文档至少包含一份代码示例
• 配图放在同目录，用相对路径引用