转载

写一篇好的技术文章有多难？

几篇让自己满意的文章。因为写一篇好的技术文章真的很难。

对于一篇好的文章来说，它有这么一些要求：

构建文章所需的理论体系
实践及代码验证
公正又有所偏爱的观点

又要注意这么一些事项：

反驳错误的观点，但不要限入争论
追求文章对自我和读者的价值
排版和语法高亮
注意错别字和专业用词

注意 ：这里所指的技术文章，不是某个问题的相关回答。而是着重于一些知识要点、架构等等，复杂的文章。

构建文章所需的理论体系

博客，光只是每天的用到知识点，那么一星期下来，怕是能记录满一本书。写篇文章可不像写代码那么轻松，首先要理清、整理自己的思路——为什么当时自己想的是 A 方法，然后才是 B 方法，又或者怎么找到 C 方法。如果能写下这个 Debug 过程，读者也许更能从中学到一些思想。而一本书吧，则是一系列相关的文章构成的合集，再加之以代码实践，以便于让读的人能更深刻的理解。写一本书的时间，可能是要上几个月，乃至几年的时间。

将生产领域的代码知识整理成体系，那就更加的困难。如在我写电子书《Serverless 架构应用开发指南》的时候，我几乎把能买到的相关中文书籍都买了，以及 Packt 出版社旗下相关的电子书。尽管只是一本托（reng）管在 GitHub 电子书，但是作为我的作品，它在某种程度上代表着我。

写文章前吧，总是得把思路理清楚。技术文章嘛，归根还是在做学问，好的技术文章必然是实践出来的。与一般的八卦文章不一样的是，技术文章必然需要有数据、实践基础，而不是道听途说或者 Copy/Paste From Google。

可是做起来并不容易，如我在写《我是如何为技术博客设计一个推荐系统》三步曲之前的文章时，大概花了一个月的时间，在设计这样一个推荐系统上。而为了验证文章的用词及算法准确性，又翻阅了一系列的文章和书籍，编写了两三个算法的 DEMO，最后才总算确认下了文章的大概。

实践及代码验证

有了一个明确的主题和想法之后，我们就需要验证它的可行性。这就好比是有一些咨询项目一样，客户已经在心里有想法，但是还需要你去实现。如我在设想 “编辑-开发-发布” 架构时，花了差不多半个月去用 GitHub + Travis CI 构建一个 DEMO 应用程序。

一般的代码验证，都还是蛮容易的。可是，有些验证则是感性的。譬如，我们要去验证 Windows、macOS 和 Linux 哪个更好用的问题，必是要找到这三个操作系统，亲自用上个把月的时间。才能知晓我说的： Windows 适合游戏与工程设计， macOS 设备 进行设计与编程，Linux 用作服务器，这句话到底是不是对的？

结论有了，那么证据也是要有的。这个时候我们就需要去证明：Mac 上没有多少游戏，又缺乏一些专业的工程软件。然后只得把相关的软件一个个的罗列出来，一对比。哦，结论真的是这样的，或者结论可能不是这样的。

结论不对，评论区里就会相当的热闹。为了评论区的热闹，总会有些人抛出错误的结论，“PHP 是全世界最好的语言”。

公正又有所偏爱的观点

没有一篇文章能让所有的人觉得满意。试图去写一篇让所有人满意的文章，看上去四不像，结果又让所有的人都不满意。

故，一篇文章应该着重于 表达作者自己的观点 ，观点应该是有理论依据的，如 “为什么 Angular 更适合于大型前端应用”，而不是重复的表达 Angular 更适合于大型前端应用。如若不想得罪那些喜欢某个框架的人，在表达的时候需要含蓄一些。如我没有使用 xxx 开发过大型应用程序的经验，或者它缺乏这些 xx 的要求。

反驳错误的观点，但不要限入争论

讨论 PHP 是不是最好的语言，本身是没有意义的。我们只是想去说服对方，而去说服对方，证明自己是的。我们讨论的从来不是 PHP 是最好的语言，而是我的观点是对的。

受教育的标志是：你可以不接受一种观点，但你能够容纳它。

容纳别人的观点，并不是一件容易的事。多数时候，可能是我们无法站在对方的角度，因为我们想象不到对方经历了什么，比如说，贫穷限制了我们的想象力。

“在互联网上，没人知道你是一条狗。”

当然了，“如果批评不自由，则赞美无意义。”做为一个作者，

成为键盘侠很容易，只需要接上网络即可。多数的论战都是没有意义的，了解一件事情的上下文很难，所以多数人懒得去了解。哪怕是你在文中反复强调了，也是如此。随后，哪怕是对方后来了解了，要在这个时候让他/她去承认错也很难。事件就变得越发的糟糕，失控就难以避免。

争论的时候，双方都觉得自己的观点是对的，对方是错的。只要是有一方觉得，“咦，好像也点道理，但是应该试一试”，那么这个时候，争论就此结束了。

至于，自己要不要适当的让步，便是另外一回事了。

排版和语法高亮

良好的排版，语法高亮样式，这两个要素可以上我们披上专业的外衣。对于我而言，保持设计的一致性，而自定义了前端显示的样式。

虽然他们并不影响文章的质量，但：

好的排版，能提供列好的阅读体验
代码语法高亮，让你看上去更加的专业。

排版，它是一种细琐的活动，做好它并不容易。而针对于大部分技术人员来说（也包含我），天生缺乏这种美感。外加之，一般的技术写作都是先用 Markdown + Git 管理，随后再使用特定的编辑工具，如 Word、微信编辑器，最后再体验上容易出现平台的不一致。我则是使用自制的工具和主题，来统一不同平台的排版。

配图。技术文章和长的文章类似，有一个不容易阅读的问题。改善用户阅读体验的一种方式是，在多个段落之间插入相关的插图，或许是可以起到视觉过渡的效果。考虑到版权问题，我开始自己去造图。

代码语法高亮，技术文章往旆少不了代码来体验真理。故，代码是检验理论和架构的标准。在文章中穿插的代码，得对读者友好，而对读者友好的常见方式是：代码语法高亮。这也是我去年，写了自己的微信公号编辑器的原因，市面上没有支持微信公号语法高亮的 markdown 编辑器。

注意错别字和专业用词

高质量的文章，对于我来说，我的文章一直存在一个错别字的问题。但是，在不影响文章本身的阅读，它可能不影响文章的质量。可是关键时候，它往往还是影响了文章的质量了。

以前总觉得呢，以后有时间去修改错别字，可并没有。但凡是说 以后改的东西，在未来基本上是不会改 。因为我们觉得，它是可以忍受的，因此优先级并没有那么高。只当我们聊胜于无，才会找一些事情出来。

那些在 GitHub 的电子书经验告诉了我，读者往往才是那些更容易找出错别字的人。我大抵是已经习惯了，这个词语是怎么写的，比如说要分清楚怎么用连接、联接，并不是一件容易的事。大部分情况下，我用的是联接。

Java 8、java 还是 j8，这个问题的答案我想大家都很清楚。作为一个工程师，要最大限度的保证用词的准确性。如 Java 8 指的是 Java 这门语言的第 8 代， java 指的应该是 Java 语言的命令行工具，j8 是用来骂人的。对于其它语言、构架，如 Python、Ruby 也是类似的， python 是指在 Python 命令行工具，可以进入 Python 语言的命令行械。