文档写作规范
基本原则
- 面向读者写作，解释业务背景与目的
- 尽量使用主动语态与简短句子
- 使用 Markdown 标准语法，避免混用 HTML
标题与层级
- 每篇文档必须包含一个一级标题
# - 章节层级不超过四级，遵循
#→##→###→#### - 标题中避免出现版本号等易变信息
内容格式
- 使用列表呈现步骤或要点
- 表格需包含表头，示例数据保持一致性
- 代码片段使用 fenced code block，并注明语言
图表与媒体
- 图片需配备替代文本，例如
 - 大型附件放置于对象存储，文档中提供下载链接
- 所有图例与标注统一使用英文
更新流程
- 在 Git 分支中提交改动并发起合并请求
- 指定评审者进行内容审核
- 合并后使用
mkdocs build验证静态文件 - 部署到目标环境，确保访问无误