上一篇文章我尽管表达了自己的一些想法但却有些观点写得不够清楚部分细节让人误解比如对自信的理解。所以我决定重新写一篇专门讲如何写技术文章的博文来与大家交流我的写作体会。本文适合有一定技术积累愿意与他人分享技术心得的读者。由于并未涉及具体技术愿意写作的读者均可以阅读。技术文章如何写作能让读者有较好的阅读体验是一个仁者见仁智者见智的问题。甚至很多人都认为根本不需要考虑读者的感受把技术写好写准确就可以了这其实就是一大误区你的写作如果只是给自己看当然我也就不多说什么但如果你的写作是给别人看就一定要考虑如何写的问题因为这是一个信息传递的过程而不是简单的记录。事实上对于一个准备开始写作的人来说通常是会认为自己写的东西一定是对的。如果一定要完全正确才可以写文章的话那就会让绝大多数人裹足不前。因此写得对不对虽然是作者应该首先要把握的但是无论作者自己还是别人都无法在写出文章公布之前知道这一点因此这不是我本文要谈的重点。我的核心观点是 好的技术文章是让符合阅读条件的读者在良好阅读体验的情况下看懂学会甚至掌握文章要传达的信息。因此需要写作中不断思考这样写读者会有什么感受。如果你的写作不能让读者有一种收获的喜悦或者阅读体验不佳那么你的写作就是有问题的。问题可能会有很多方面我们一点点分析。要告知读者文章适合什么人读首先要告知你写的文章适合什么人读这尽管不是最重要的条件但你是打算一开始就告诉读者这文章的适读人群还是让读者需要读完文章后再自己去判断这文章可不可以看得懂两者在阅读体验的感觉是完全不一样的。通常一篇文章对于某个读者不是太浅就是太深。正好是自己不了解的技术知识自己有兴趣而又能通过阅读看得懂的文章才是适合的好文章。因此由于读者层次不同你的文章给什么人看的定位就很重要。你把你的文章放到了博客园首页上那就意味着不管什么层次的读者都可能点击进去。你如果不告知读者这个内容至少需要具备什么样的条件才能阅读对于一篇有一定技术难度的文章初学者去阅读它怎么可能高兴得起来。反之如果你在一开头就写明此文必须要有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重申一下我的观点 好的技术文章是让符合阅读条件的读者在良好阅读体验的情况下看懂学会甚至掌握文章要传达的信息。我写了一些注意的事项都算不上新鲜内容也未必全面只能算是抛砖引玉。总的说来如果你的写作是为了分享那么一定要时刻考虑你的读者有了这样的心态不愁写不好技术文章。注对于一些如新闻类、搞笑类的博客不在此文指向的范围内。本文只针对技术交流用的博客或者图书的写作。