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

image.png

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

1、标题下无综述性语句

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

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

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

怎么写这部分: 综述性内容可以涵盖以下几项(包括不限于):

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

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

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

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

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

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

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

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

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

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

6、比较多的贴代码

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

7、篇幅即资源

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

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

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

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

最后回答一个问题,为毛我们写作模板要用Word:

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

其他问题也还有很多,具体情况具体分析了~~

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

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

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

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

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

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏祝威廉

这些年,我工作上走过的路

我走过了毕业季,创业征途,踏进开源之路,转型进入大数据,到最后有缘接触机器学习。每个章节,我都会提及对应那个阶段对技术的感悟,自己做的一些具体事情。

22620
来自专栏腾讯社交用户体验设计

项目同步管理法 - 设计师辅技手册(三)

14120
来自专栏极乐技术社区

小程序 · 一周报

6 月 21 日,微信升级小程序插件能力:开放插件登录能力;支持在插件内使用微信支付能力,便于用户在插件内完成预订、购买等流程;新增全页面插件,开发者可开发完整...

12200
来自专栏机器之心

业界 | 为什么Jupyter是数据科学家们实战工具的首选?

大型综合巡天望远镜(Large Synoptic Survey Telescope,LSST)坐落在智利安第斯山脉帕穹山脊,计划 2022 年启用。它将自动探测...

10930
来自专栏Java进阶干货

工作2年半跳槽面试阿里,成功拿到offer,凭什么?

2015年刚毕业的我,进入了一家小小的公司实习工作,在学校学了三年软件开发的我,还是想去寻找一份互联网行业的工作,这样更能学以致用发挥自己的特长。一直到18年三...

42010
来自专栏CDA数据分析师

业界 | 为什么Jupyter是数据科学家们实战工具的首选?

大型综合巡天望远镜(Large Synoptic Survey Telescope,LSST)坐落在智利安第斯山脉帕穹山脊,计划 2022 年启用。它将自动探测...

10720
来自专栏华章科技

谁说不能用 Python开发企业应用?

语言多元化是PayPal编程文化中一个重要的组成部分。在C++和Java长期流行的同时,更多的团队选择了JvaScript和Scala。同时,Braintree...

18420
来自专栏牛客网

阿里凉经 简历+1面+2面

Java final volatile 关键字 volatile指令重排序 举个重排序例子

34010
来自专栏CDA数据分析师

对自己的上网搜索记录进行爬虫是怎样一种体验

原作者 Walker Harrison 编译 CDA 编译团队 本文为  CDA 数据分析师原创翻译作品,转载需授权 前言 国外习惯用 Google 进行搜索,...

288100
来自专栏腾讯移动品质中心TMQ的专栏

管家12大版本质量把控秘籍

六脉神剑秘籍 说起一年一度的管家大版本,那可是一个浩大的工程,管家各大中心都会参与,变更代码线多,版本稳定期久,对各个中心正常的单周迭代需求合入影响大,这质量把...

27660

扫码关注云+社区

领取腾讯云代金券