Skip to main content

技术文档写作规范

众所周知,风格统一、语法规范的排版,能使文章更加易读,降低沟通的成本。

文章结构

撰写技术文章时,可以参考以下的结构层次:

# 文章标题

一两句话介绍本文的内容。

## 效果

请大致介绍 demo 的用法,并展示效果。

## 原理

请逐步介绍原理。

## 总结

做一个简单的总结。

## 参考与致谢

- [参考 1](参考 1 的链接)
- [参考 2](参考 2 的链接)

排版规范

段落

  • 使用 Markdown 语法时,首行无需缩进
  • 段与段之间需要有空行区分

需要添加空格的场景

  • 中文与英文、数字之间:

    错误:Qt生成器是一个针对C++的跨平台IDE
    正确:Qt 生成器是一个针对 C++ 的跨平台 IDE

  • 数字与单位之间:(但数字与百分号间不需加空格)

    错误:其频率为 72MHz,占空比为 50 %。
    正确:其频率为 72 MHz,占空比为 50%。

  • 普通与特殊字符(链接、加粗、斜体等)之间:

    这个 字体 使用了加粗样式 请 点击这里 进行订阅

  • 英文半角标点之后:

    Hello, world

  • 中文与破折号之间:

    Markdown - 一种高效的写作方式

文本样式

  1. 中英文混排时,默认使用中文全角标点
  2. 中英文混排中,如果出现整句英文,则此句内使用英文半角标点
  3. 行内链接一般使用加粗,以提高阅读性
  4. 使用准确的专有名词:

    错误:使用 github 登录
    正确:使用 GitHub 登录

  5. 中文使用直角引号,代替普通引号:

    错误:华广机器人队,也称为“野狼队”
    正确:华广机器人队,也称为「野狼队」

  6. 不重复使用标点以强调

写作风格

  • 如无必要,勿增实体
  • 为了提高可读性,尽量避免使用长句,可拆分为多个简单句
  • 论点要有论据支持,避免只说理不举例

参考与致谢

本篇文章受 CC BY-NC-SA 4.0 协议保护,转载请注明出处。