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 协议保护，转载请注明出处。