技术书写作你要知道的几件事

写作是非常系统性的工程，需要作者和策划一起设计写作的路径，根据读者的阅读情景、需求考虑内容的呈现形式。如果可以切实从读者出发，首先满足知识性需求，其次满足阅读的舒适度，那么这本书应该不差。我根据评审的书稿，简单总结技术类图书常见的一些问题，希望大家在写作的时候注意避免。

1、标题下无综述性语句

章节开篇（一级和二级标题下）没有综述性内容，尤其纯技术书作者往往直接开始写内容，这样的作者往往缺乏整体性、全局高度的视角，需要在写作时经常审视自己的书稿是否有这样的不足。

综述性内容的必要性：这些内容可以让读者知道你要讲什么内容、这个内容的大体轮廓和必要的上下文。一是可以让他提前做好阅读阅读准备和已有知识上下文，带着问题和好奇心去阅读；二是可以让他对整体有初步的认知，也是粘合各个知识点的“粘合剂”，不要小看这部分；三是大标题下没有文字介绍，非常突兀，其实深层次原因就是整体性的思考有欠缺。

这部分通常可以涵盖技术功能、背景、学习价值等。

怎么写这部分：
综述性内容可以涵盖以下几项（包括不限于）：

一般可以是定义、功能
章节涵盖的内容介绍（会从哪几方面介绍）
阅读的价值和收益，比如更深入了解原理，知道XX如何操作，为何这么操作之类
其他需要读者知道的上下文，比如行业背景、最新进展等读者有必要了解的背景性内容。

注意：以上内容可以包含一项或者几项。

2、标题下没有文字，上来就是代码或者图、表

一般来说，在写作的时候要避免在章节开头上来是图或者代码，因为这样一是突兀，二是读者没有get到你的意图就看图和代码，是不能有效获取其中的信息的，也不能构建自己的学习上下文，不能带着目的去学习。

3.、图、表、代码不在正文交代是什么

图、表、代码清单都要在正文说下是什么，之后再给出，也是让读者有了解的心理准备。给出图、表、代码清单之后，再结合这些要素做必要的分析和总结。借用作者同学的话，是总-分-总结构。

4、代码清单不加注释或者注释是英文

书中的代码就不要讲求“干净”而不加注释。你要考虑读者是初学者，他需要结合注释来理解，代码之后可以详细分析，分析的语句建议加注释，做呼应。
注释一般不建议是英文，读者英文水平不同，而我们也是中文书，所以你懂得。

5、操作不分析为什么，像流水账

好的书不但要告诉怎么操作，还要告诉为什么这么操作；如果情况有几种，最好要分情景来讲。只写操作，就是给他鱼，告诉他为什么才是“授人以渔”，这也算是“画饼”，学习的动力。

6、比较多的贴代码

技术人员往往看重操作和实现，但是读者更愿意看到你的思路和分析，代码很多，github上一堆，而出书不同，我们是老师，我们要讲思路、讲为什么，这个是比较重要的增值项之一。

7、篇幅即资源

任何时候都要记住“篇幅即资源”。所讲的内容一定要紧扣主题。有的作者部分内容可能讲得比较随性，这样即浪费篇幅，稀释有效观点，也让读者产生不好的阅读体验，可能放弃本书。

一般什么样的内容是浪费篇幅的呢：

容易获取而且常见的内容。例如，单纯罗列软件版本历史，如非必要，还是精简为好。很多人看别人的书有，自己也要加，这个是属于没有思考型；一般历史性内容，除非是非常新的技术，一般都不用讲，这些都是容易获取而且常见的内容。
和章节所在主题关联不大。这样的内容一般都是外延扩展太大，而没有必要和直接的联系。如果作为“拓展阅读”是可以的。
内容过时，技术更迭较快，如果受众不多，不建议讲，可以添加链接或者给出公众号放在上面。

罗里吧嗦讲了一堆，其实大概就是写作时要注意整体性描述、思路分析、读者阅读感受。

最后回答一个问题，为毛我们写作模板要用Word：
* Word的批注功能很nice，我们编辑可以在上面加批注，一般是写作问题、改进建议
* Word的修订功能不要太好啊，你可以看到编辑修改了啥，当然版式的调整编辑一般不会开，你看不到她帮你做了多少工作，开了满篇花，好咩？
* Word的内容编辑比较容易统一调整，也方便生成目录。

其他问题也还有很多，具体情况具体分析了~~
* 同一个拼写大小写不统一、不规范
* 错别字多，虽然文字编辑会全书审校，但是问题太多了，总会有漏下的
* 避免写成产品说明书，不要介绍很多组件、参数，但是不介绍关联、流程和机制。
* 如果涉及自家产品，切忌写成软文，比较好的做法是价值驱动、痛点驱动，可以写解决了什么技术难题，解决思路与实现分析。
* 引用，引用是为了说明自己的观点，不是别人的内容要作为内容的必要组成部分。

引用可以体现在脚注，并取得原作者授权。如果吸纳了观点等，可以放在参考资料或者参考文献。

写作绝非易事，为了读者的利益，为了自己的品牌，筒子们，加油啦~~

致谢：
本人才疏学浅，匆匆成文，本不打算开源，唯恐误导各位，但是小程大大说还是有点价值，打算传播下，所以各位看官就看到本文了，感谢小程大大。

微信号：xishuihua2008，欢迎同行、写过书的作者、即将写书的作者交流与探讨。
最近忙定稿，回复可能不及时，请见谅。