跳到主要内容

技术写作风格指南

· 阅读需 4 分钟
Yang Chu
Yang Chu
Product Manager @ Cyritex
Yakun Wu
Yakun Wu
VP @ Cyritex

本文档旨在规范技术文档的写作风格，确保文档的一致性和可读性。

空格使用规范​

中英文之间的空格​

  • 在中文和英文单词之间应加入空格

    • ✅ 正确：我们使用 Docker 来部署应用
    • ❌ 错误：我们使用Docker来部署应用

  • 在中文和数字之间应加入空格

    • ✅ 正确：系统需要 2 GB 内存
    • ❌ 错误：系统需要2GB内存

特殊情况​

标点符号规范​

中文标点符号​

  • 中文文句中使用全角标点符号

    • ✅ 正确：请按照以下步骤操作：
    • ❌ 错误：请按照以下步骤操作:

  • 中文文句中的逗号、句号等标点使用全角

    • ✅ 正确：安装完成后，请重启系统。
    • ❌ 错误：安装完成后,请重启系统.

英文标点符号​

  • 英文句子中使用半角标点符号
    • ✅ 正确：The installation is complete. Please restart.
    • ❌ 错误：The installation is complete。Please restart。

代码相关​

  • 代码、命令行示例中的标点使用半角符号
  • 代码块前后应空一行
  • 行内代码使用反引号（`）包裹

格式规范​

标题格式​

  • 标题层级不应跳级使用（如：h1 后直接使用 h3）
  • 标题应简明扼要
  • 标题从 h1 到 h6 依次降级使用

列表格式​

  • 无序列表使用 - 或 *
  • 有序列表使用 1. 2. 等数字标记
  • 列表项应保持对齐
  • 列表层级不宜过深（建议不超过三级）

专有名词规范​

  • 产品名称、技术名词应保持大小写一致

    • ✅ 正确：JavaScript、Docker、Kubernetes
    • ❌ 错误：javascript、docker、kubernetes

  • 首次出现的专业术语应提供解释

  • 同一个概念在文档中应使用统一的称谓

其他建议​

文档结构​

  • 在文档开始提供简要说明
  • 适当使用图表辅助说明
  • 重要信息使用提示框突出显示
  • 较长文档应有目录导航

写作风格​

  • 使用简洁、清晰的语言
  • 避免使用过于口语化的表达
  • 保持客观、专业的语气
  • 使用主动语态，避免被动语态

文档维护​

  • 定期检查文档的时效性
  • 及时更新过时的内容
  • 保持版本信息的更新
  • 注意文档间的交叉引用准确性

示例展示​

以下是一个规范的文档片段示例：

# 产品介绍

本文档介绍了 Docker 容器的基本概念和使用方法。

## 什么是 Docker ？

Docker 是一个开源的应用容器引擎，让开发者可以打包他们的应用以及依赖包到一个可移植的容器中。

## 主要特性

- 轻量级的容器虚拟化
- 跨平台支持
- 版本控制和组件重用