技术文章写作规范

最后更新于:2022-04-02 04:27:19

## 技术文章写作规范 ![](http://cdn.aipin100.cn/a60583cd030e272b8de3e54ddcd18652) 网上有大量的技术文章,内容质量参差不齐,有的传播广,有的却默默无闻,而那些传播最广的不一定是内容质量最高的,而默默无闻的往往也不是因为内容质量低。 还有一些文章,都是一些碎片化的知识内容,有的甚至有明显的错误,有的阅读起来很费力,引用的内容找不到出处和证明……,等等这样的问题,这让我们平时在网上搜寻资料时相当不容易。 鉴于此,本文遂总结一些技术文章的写作规范和技巧,掌握这些有利于提高写作质量。 ***** ### 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
';