技术写作规范是什么
写作规范（Style Guide）统一一批看似琐碎、实际高频出错的细节：术语用哪个说法、数字与单位怎么写、界面元素与代码如何标注、标题层级怎么排、语气与人称如何选择。它的收益不在单篇文档，而在整个文档集的一致性——读者阅读成本降低，翻译与本地化成本下降，评审时也不必再为格式争论。
基本信息
| 规范内容 | 术语表、格式规则、代码与界面元素标注约定、语气与人称、标点与数字写法 |
|---|---|
| 适用范围 | 产品文档、界面文案、错误提示、对外公告与培训材料 |
| 落地方式 | 规范文档 + 自动检查规则 + 评审清单三方配合 |
| 维护责任 | 指定一名写作规范负责人，定期收集争议点并更新 |
| 参考框架 | 可参考业界通用风格指南（如 Google、Microsoft 的写作风格指南）并结合内部术语 |
典型使用场景
- 新同事写第一篇文档时对照规范，减少返工
- 多人协作同一文档集时统一术语与格式，避免同物多名
- 本地化与翻译前整理术语表，提高翻译一致性
- 把规范条目转成自动检查规则，取代部分人工评审
- 错误提示与界面文案评审：统一语气与用户视角
规则示例
规则示例
术语：统一用“主从复制”，不再混用“主备/主从库”等说法
界面元素：按钮用【确定】标注，路径用 > 连接，如【设置】>【网络】
代码：行内代码统一样式，示例需完整可复制，变量用占位符尖括号
数字与单位：数字与单位间加空格，如 100 MB；时间统一时区标注
标题：句子式、避免多重嵌套，同一层级不超过三级规则与落地手段
| 规则类型 | 示例 | 落地手段 |
|---|---|---|
| 术语统一 | 同一概念只用一个说法 | 术语表 + 检查工具词典 |
| 格式规范 | 标题层级、列表缩进、行尾空格 | Markdown lint 自动检查 |
| 示例约定 | 代码块标注语言、可复制、含注释 | 评审清单 + 语法检查 |
| 语气人称 | 面向用户用第二人称，避免“我们” | 抽查与评审 |
| 数字写法 | 单位、精度、时区、日期格式 | 词典与模板 |
规范要短到能被读完：把几十页的规范压缩成一页核心规则加一份术语表，其余作为附录。规则越少越可能被真正执行，后续再按实际争议点增补。
规范与自动检查要同源维护：术语表和格式规则一旦更新，同时更新检查配置，否则工具仍按旧规则报错，作者会逐渐不信任检查结果。