技术文章写作规范
最后更新于：2022-04-02 04:27:19
## 技术文章写作规范
网上有大量的技术文章，内容质量参差不齐，有的传播广，有的却默默无闻，而那些传播最广的不一定是内容质量最高的，而默默无闻的往往也不是因为内容质量低。
还有一些文章，都是一些碎片化的知识内容，有的甚至有明显的错误，有的阅读起来很费力，引用的内容找不到出处和证明……，等等这样的问题，这让我们平时在网上搜寻资料时相当不容易。
鉴于此，本文遂总结一些技术文章的写作规范和技巧，掌握这些有利于提高写作质量。
*****
### 1. 保持简洁和准确语义
“这儿多了一个空格，下面 sql 语句执行失败了。”
“这儿多了一个空格，导致下面 sql 语句执行失败。”
你感受一下这两句话，表达的是同一个意思，但是明显下面一句话读起来更好，好在哪里又似乎说不出来，其实下面一句话，意思更加明确。
大多数时候，我们看文字，看东西的时候，都是一目十行（**眼睛和大脑并不同步，阅读十行，但其是大脑并没有逐字地去看**），模糊的意识、潜意识的（**很多时候大脑是根据残存的记忆或过往的经验去接收和理解信息的**），如果表达不清晰，很容易就理解偏了意思，而如果文章表达的意义简单易懂，那么我们一目一行的看过去就不会出现问题，否则有的段落我们还要来来回回看几遍才行，这是失败的写作。
观点鲜明，用词直接，简单，语句通顺，让人读起来不吃力，感觉就是这般样子，这就是行文流水的境界吧。
如果我们需要表达某个观点时，请用语义更加明确，直接，简单的方式表达出来。这就是说话的语义化。
> 还有，能用肯定的就不要用双重否定。
* * * * *
### 2. 作者应该保持中立
当一件事物有两种或多种观点时，作者应该先阐述每一种观点，将评判留给读者自己去判断。不要加入自己的观点以倾向于某一种，从而客观影响读者自己的判断。
当然，不要误会，要求作者保持中立并不是说作者不能没有自己的看法，只是说不要把自己的意愿强加给读者，而要给读者开放的思想。当作者详尽的阐述完后，最后再表明自己的观点和看法，这是可以的，我们鼓励这样。但不要发表没有依据的观点，和加入自己的意志来客观引导读者，这正是我们反对的。
同时还应当注意的是，当作者的观点不被读者接受，甚至收到批评的时候，要能够包容不一样的声音，因为：如果批评不自由，则赞美无意义。
* * * * *
### 3. 语气不应过分带有个人色彩
我认为，技术类文章应该是严谨的，语言用词都应该是准确的。这里所说的严谨不是说文章一定要保持那种教条式的刻板，幽默有趣也未尝不可，但是不能过了，如果文章风格和字里行间透露着作者个人个性化的东西（如：作者的口头禅、俗语、过分俏皮卖萌和无厘头以及嘻哈风），那么这样的文章就算再好，受众也不会很广。
技术文章不同于一般性文章，它的受众没有界限，没有年龄、性别、地域、种族的界限，都应当被每个人平等的触及到的。所以在写技术文章时，作者的文风应该保持严谨，不应该过分加入自己的性格色彩，这样的文章才易于阅读和广泛传播。
*****
### 4. 多采用分段的方式
不同于写作文和散文，技术文章对格式没有特别的要求，只要保持简洁，结构清晰就可以了，而要想做到结构清晰，最好的方式就是分段。类比技术文档，技术文章其实是最容易采用分段写作的了。
如每一个大的技术点都可以作为一个大的段落，并且为每一段起一个标题，根据内容长短和复杂度，甚至还可以以章节的形式分篇书写。多尝试，很快你就能掌握这个技巧，这样你写的文章再也不会是那种冗长，密密麻麻，令人生畏的了。
*****
### 5. 写作时间/背景
很多时候作者有必要给出写作的时间，必要的时候还需要交代写作的背景，因为随着时间流逝，很多东西可能都发生变化了，如果作者写作时备注清楚了写作时间，将会在未来给读者阅读时提供帮助和参考，以让其更好的理解内容。
另外考虑到软件行业发展迅速，环境更迭往往会使旧代码很快过时，所以对于重要的代码演示部分，作者甚至有必要给出自己当时测试的环境信息：机器型号，依赖库，软件版本等详细信息。这样做不仅显得更加专业严谨，也方便了读者，避免了读者调试运行时结果与文章中不一致的问题。
*****
### 6. 引用来源
如果你的文章有引用外部资料或写作时参考了其它资料，就务必要在文中或文末给出来源，包括但不限于，参考资料、文献、实验数据、佐证等。有了这些文章才算是完整的，立体的，才是可信的，因为它确保了成文有据可依，有源可溯，这对读者来说是非常有益的。并且交代出处也是对读者负责和对原引用的一种尊重的体现。
* * * * *
本文会一直保持更新状态，大家有好的心得见解可以在下面留言讨论。
*****
### 参考资料
[中文技术文档的写作规范 - 阮一峰的网络日志](http://www.ruanyifeng.com/blog/2016/10/document_style_guide.html)
[mzlogin/chinese-copywriting-guidelines: Chinese Copywriting Guidelines：中文文案排版指北（简体中文版）](https://github.com/mzlogin/chinese-copywriting-guidelines)
[这个房间的消音高达99.99％！安静到能听到自己肠胃蠕动的声音！](https://www.365yg.com/a6536155986007163396)
[信息与大脑 · 产品设计 · 看云](https://www.kancloud.cn/xiak/product/679861)
[中文文案排版指北 chinese-copywriting-guidelines/README.zh-CN.md at master · sparanoid/chinese-copywriting-guidelines](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.zh-CN.md)
> 空格：「有研究显示，打字的时候不喜欢在中文和英文之间加空格的人，感情路都走得很辛苦，有七成的比例会在 34 岁的时候跟自己不爱的人结婚，而其余三成的人最后只能把遗产留给自己的猫。 毕竟爱情跟书写都需要适时地留白。
> 作为一名工程师，最被低估的技能是记录。说真的，如果有人可以教我怎么写文档，我会付钱，也许是 1000 美元。 —— [程序员的酒后真言 - 阮一峰的网络日志](https://www.ruanyifeng.com/blog/2021/06/drunk-post-of-a-programmer.html)
[访谈：TC无处不在，只是我们没有发觉 | 技术传播](https://mp.weixin.qq.com/s?__biz=MzU3OTM4OTkzNQ%3D%3D&chksm=fd679443ca101d556b02edfe5725d31beed93704431a2a74f067ce1fac0db65a2e693e5396bd&idx=1&mid=2247484611&scene=21&sn=c49b54711d04962ca885fbae709cd974#wechat_redirect)
* * * * *
last update：2020-06-20 18:53:12
';