技术文档写作规范
众所周知,风格统一、语法规范的排版,能使文章更加易读,降低沟通的成本。
文章结构
撰写技术文章时,可以参考以下的结构层次:
# 文章标题
一两句话介绍本文的内容。
## 效果
请大致介绍 demo 的用法,并展示效果。
## 原理
请逐步介绍原理。
## 总结
做一个简单的总结。
## 参考与致谢
- [参考 1](参考 1 的链接)
- [参考 2](参考 2 的链接)
排版规范
段落
- 使用 Markdown 语法时,首行无需缩进
- 段与段之间需要有空行区分
需要添加空格的场景
- 中文与英文、数字之间:
错误:
Qt生成器是一个针对C++的跨平台IDE
正确:Qt 生成器是一个针对 C++ 的跨平台 IDE
- 数字与单位之间:(但数字与百分号间不需加空格)
错误:
其频率为 72MHz,占空比为 50 %。
正确:其频率为 72 MHz,占空比为 50%。
- 普通与特殊字符(链接、加粗、斜体等)之间:
这个 字体 使用了加粗样式 请 点击这里 进行订阅
- 英文半角标点之后:
Hello, world
- 中文与破折号之间:
Markdown - 一种高效的写作方式
文本样式
- 中英文混排时,默认使用中文全角标点
- 中英文混排中,如果出现整句英文,则此句内使用英文半角标点
- 行内链接一般使用加粗,以提高阅读性
- 使用准确的专有名词:
错误:使用 github 登录
正确:使用 GitHub 登录 - 中文使用直角引号,代替普通引号:
错误:华广机器人队,也称为“野狼队”
正确:华广机器人队,也称为「野狼队」 - 不重复使用标点以强调
写作风格
- 如无必要,勿增实体
- 为了提高可读性,尽量避免使用长句,可拆分为多个简单句
- 论点要有论据支持,避免只说理不举例
参考与致谢
本篇文章受 CC BY-NC-SA 4.0 协议保护,转载请注明出处。