技术文章如何写，才能有较好的阅读体验？

(点击上方蓝字，快速关注我们)

作者：伍迷

www.cnblogs.com/cj723/archive/2012/03/15/2396422.html

本文适合有一定技术积累愿意与他人分享技术心得的读者。由于并未涉及具体技术，愿意写作的读者均可以阅读。

技术文章如何写作能让读者有较好的阅读体验，是一个仁者见仁，智者见智的问题。甚至很多人都认为根本不需要考虑读者的感受，把技术写好写准确就可以了，这其实就是一大误区，你的写作如果只是给自己看，当然我也就不多说什么，但如果你的写作是给别人看，就一定要考虑如何写的问题，因为这是一个信息传递的过程而不是简单的记录。

事实上，对于一个准备开始写作的人来说，通常是会认为自己写的东西一定是对的。如果一定要完全正确才可以写文章的话，那就会让绝大多数人裹足不前。因此，写得对不对虽然是作者应该首先要把握的，但是无论作者自己还是别人都无法在写出文章公布之前知道这一点，因此这不是我本文要谈的重点。

我的核心观点是：

好的技术文章，是让符合阅读条件的读者，在良好阅读体验的情况下，看懂学会甚至掌握文章要传达的信息

。因此，需要写作中不断思考，这样写，读者会有什么感受。如果你的写作不能让读者有一种收获的喜悦，或者阅读体验不佳，那么你的写作就是有问题的。问题可能会有很多方面，我们一点点分析。

要告知读者文章适合什么人读

首先要告知你写的文章适合什么人读，这尽管不是最重要的条件，但你是打算一开始就告诉读者，这文章的适读人群，还是让读者需要读完文章后再自己去判断这文章可不可以看得懂，两者在阅读体验的感觉是完全不一样的。通常一篇文章对于某个读者不是太浅，就是太深。正好是自己不了解的技术知识，自己有兴趣，而又能通过阅读看得懂的文章才是适合的好文章。因此由于读者层次不同，你的文章给什么人看的定位就很重要。

你把你的文章放到了博客园首页上，那就意味着不管什么层次的读者都可能点击进去。你如果不告知读者，这个内容至少需要具备什么样的条件才能阅读，对于一篇有一定技术难度的文章，初学者去阅读它，怎么可能高兴得起来。

反之，如果你在一开头就写明，此文必须要有A、B、C的知识，否则还是不看为妙，那么误入的读者至少可以不需要继续往下看，或者有个心理预期，可能看不懂，不过反正自己也没到那个层次，没什么关系。

如果将写作的具体技术难度分为九级（九级最高），你打算写一篇难度为七级的文章。此时，你不应该考虑水平在一、二、三级的读者，而是将四、五、六级的读者作为目标群，因为你的难度应该要让读者稍微费点力就够得着的，而不是那种根本看不懂的人，这样的定位才会更有针对性。如果你写的内容连二、三级读者都能读懂，那就说明实在是太啰嗦了，细节描述过多。如果只有七级水平的读者才能看得懂，那通常又是因为描述过于简洁而忽视了细节。这两种情况你的文章价值都会大大缩水。

清晰明白地指出文章适合什么样的人读，这有很多方法。可以是标题、摘要或者文章开头，只要达到提醒的作用，不要去浪费非目标读者的时间就对了。

另外，如果可能，还应该在文章末尾提供继续深入学习的建议，比如之后应该阅读什么书，看什么文章等。也就是说，你可以为你的读者指明了接下来学习努力的方向。

总之，你在一开头就告知此文章适合什么人读，帮助了读者节约了判别的时间，这是一个非常好的开始。

写作内容的难度层级递进

不要一上来就是关键知识点，那虽然是一种风格，但却违背了知识（或者说信息）传递的规律。

你在大街上看到了一漂亮姑娘，想让她成为自己的女朋友，你不能直接上去说“做我女朋友吧”，除非你开着法拉利或许可能。你首先要和她认识，并得到联系方式。简单的办法就是去搭讪。搭讪时如果直接说“给我你的手机号如何？”显然也是不合适的，除非你长着贝克汉姆的脸兴许可以。所以你得说点不让人反感的话。比如：“你那iphone如果开启手势功能，就不需要频繁按Home键了。不信？你看我的……”

举技术写作上的例子。在讲算法时间复杂度的知识点时，你当然可以直接讲时间复杂度的定义(就像大多数数据结构教材一样)，可这是很让读者，特别是刚学的人迷惑的，为什么要强调这个呢？而且由于一上来就是对大O阶推导，理解比较困难，读者的体验就相当差。

我在《大话数据结构》书中讲解的办法是先举了从1加到100的算法例子，对比容易想到的算法和高斯算法的差异，来引入算法优劣间的差异，并详细解释了函数渐近增长的原理，最后再来给出时间复杂度的定义，以及推导大O阶的方法。由于读者理解了函数渐近增长的原理，再去理解时间复杂度就变得容易了，这就是层级递进的作法。

运动员比赛前都需要热身，男女亲热前也需要前戏。同样，为了让读者进入阅读状态，用一些简单的例子来预热，用一些稍难的例子来铺垫，然后引出要讲解的重点，这样可以更好的达到讲解好知识的目的。

得用读者可以理解的语言，而不是你认为好的语言

微博上有这样一个段子。一位老太太想知道什么是Facebook，约旦VC Ahmad Takatkah的解释：

1)Facebook是一份报纸；

2)这报纸要在电脑或手机上看；

3)报纸里只有家人和朋友的新闻，第2页是儿子的、第3页是妹妹的…

4)关于他们的新闻他们自己写；

5)其中有一页是你自己的，想写什么想让谁看你说了算；

6)报纸第1页，是全部内容摘要。

怎么样，是不是感觉很不错？如果为了让老太太理解Facebook，去提什么这是一家社交网站，它可以向亲朋好友分享照片、视频和个人信息等很IT化的语言，她一定是非常困惑。她可能接着就会问“什么是社交网站”、“什么是视频”等问题了。

同样，你如果想让你的读者阅读体验好，就一定要用适合他们的文字，而不是你自己喜欢的文字，哪怕你的文笔相当棒。

这一条可能是最重要的一点，信息的传递最终都是为了让读者理解你的意图。写作时，一定要时刻想着用适合读者的语言来表达。

一图值千言

用上千个字描述不明白的东西，很可能一张图就能解释清楚。比如我在讲解数据结构的归并排序时，写了很多文字来说明排序的原理，但如果没有下面这样一张图，可能都是遗憾的。很多人也许就在看图的一瞬间，就明白了前面的迷惑原来就是因为大脑里没有这样一个类似的数据变换概念造成的结果。

当然，也不一定要一张完整的大图，也可以是多张小图和相应的文字来解释一个动态的过程。比如下面是进解二叉树前序遍历的部分截图。通过文字加分解图的方式，对于一个知识点的说明还是不错的办法。当然，最好的办法是用动画的形式来表现，目前暂时还不容易做到。或许未来的电子书，应用动静结合的方式将会让读者有更加舒适的阅读体验。

不过你毕竟不是在画漫画，图的目的是为了更好的说明问题，如果只有图，没有抽象的文字来准确的表达你的意图，可能就本末倒置了。

总之，在分析讲解时，能够通过一些图形化的表达来说明问题一定会比纯文字的表达更加容易理解。

代码分解讲解

时常看到这样的情况，写作者会把超过100行的大段代码贴在博客中，然后在前或后面用一段的文字说明自己要分享的观点，这是很难让读者感觉到愉悦的。因为要认真读懂你的代码以及你文字表达的意思，读者就必须要频繁上下翻页，这可是一件非常不爽的体验过程。

解决办法还是有的。不妨将大段的代码分解成一个小函数一段说明文字，甚至是一句代码一段说明文字的方式来讲解。这样的好处就是说明的文字就在代码的旁边，能够很容易就查看到了。

另外，对于代码的讲解有时需要模拟其运行时的状态，根据某一断点时刻的变量变化情况描述来说明这个函数或这个循环是在干什么。这更加需要分解代码来分析。

很明显，本来是贴一段代码，再写一段文字就算是完事的工作，现在需要一段一段的说明，一定是更耗费精力和时间，但这是很值得的工作。这也是我在本文一再强调的是为读者考虑而非为自己考虑的写作方式。

多用章节条目段落

除非你的文章很短，不然我都建议尽量多分章节条目和段落。这样读者阅读不会太累。

一些单机游戏，比如极品飞车或实况足球等游戏，一般一局的时间不会超过5分钟。为什么要这样设置，因为这可以让玩家精神集中一段时间之后得到一定的时间休息。

同样，读者读的文字，如果几千个字就组成一段话，那将是相当累的，多半情况就是阅读不完就拉倒了。如果几千个字分成六、七节，每一节各有四、五段，那就会好很多。读者可以在每读完一小节时，体会一下其内容，或者去上趟厕所。

即便是阿凡达这样的极品大片，也是有尿点时间的，你的文章为什么不这么做呢？

当然，章节条目最重要的作用是有利于帮助读者了解整个文章的脉络体系，更好的把握这篇文章讲解的内容是什么。

排版、背景颜色、字体颜色、大小、类型的处理

这些本身就是一门学问，都可以专门写本书了。好的排版是没有标准、也没有止境的，可以做到千变万化、赏心悦目。我非这方面特长，就不展开了。

不过，对于大多数读者来说，比较传统的排版就能够取得比较好的阅读效果，反而过于标新立异，比如黑底白字，艺术字体等方式是不可取的。

善待读者

这个本不应该成为一条，但还是觉得有必要提一下。你写给自己看，把自己写成上帝也没人管你。可是你是写给别人看的，你的目的不是打击读者，而是帮助读者，那么写作中以及之后的回复评论中，谦虚或与人为善的态度才是更值得提倡的。

人生来就是不公平的。有些人天生聪明，读了最好的小学、中学、大学，工作在中国IT10强，甚至是世界IT10强的企业。他们自身可能也是非常努力，但由于他的一分努力总是抵得上别人两分甚至五分的努力，加上只会越来越好人文环境和越来越多的技术资源，就算有点坎坷，最终成为技术大牛几乎就是必然。

一个愿意分享技术心得的大牛相当难得，这一点一定要非常肯定。能让大家佩服的原因，还是因为他持续发表优秀文章的结果。但他们又时常会在表达正确技术观点之时，顺带骂几句犯错误的小菜鸟。这种自然而露的优越感总会让一些暂时还学无所成的读者垂头丧气。

我此前就说过，人都是从小长到大的，谁TM没有幼稚过。当你成为了技术牛人的时候，不应该忘记自己当年也是有过技术困惑，也是有过挣扎、努力、失败的情况，体谅一下那些刚刚起步的小兄弟、理解一下他们的无知和浅薄为什么就不可以呢？他们中的有些人可能永远也无法成为技术牛人，但他们依然可以在自己的岗位上做出应有的贡献。你的文章如果打击了一些人，可能就真的伤害了他们，反之，如果可以帮助到其中的一些人，其实也是你对社会的贡献，也是你的价值体现。

其实我也知道，我的这段文字改变不了大牛的态度，他们该怎么写还怎么写。只不过我觉得上天给了他们140分的智慧，他们却只做到了120分的成绩，实在是非常可惜。也就是说，我本觉得他们可以做得更加好。不信？翻看一下曾经的日记，是不是早已经忘记了当年那壮志豪情的理想了呢？

OK，重申一下我的观点：

好的技术文章，是让符合阅读条件的读者，在良好阅读体验的情况下，看懂学会甚至掌握文章要传达的信息。我写了一些注意的事项，都算不上新鲜内容，也未必全面，只能算是抛砖引玉。总的说来，如果你的写作是为了分享，那么一定要时刻考虑你的读者，有了这样的心态，不愁写不好技术文章。

注：对于一些如新闻类、搞笑类的博客不在此文指向的范围内。本文只针对技术交流用的博客或者图书的写作。

看完本文有收获？请分享给更多人

关注「伯乐在线」，看更多精选 IT 职场文章