码字的注意事项

 写实用技能类文档和工具书，踩过的一些坑，记录下来，也给需要写文章的朋友们做个参考，写完检查一下，减少编辑的工作量，也省得自己反复修改，减少沟通成本。总结如下：

1. 内容

 内容实用，有实例，大白话，写出读者痛点。
(1) 确定针对读者群体
 不存在上下通吃的文章，需要确定主要的读者群体，读者已知的问题不再重复，未知的问题要解释清楚。
(2) 单个主题内容不要过多
 很少有书把深度学习和机器学习写在一起，对于技能类工具书或者文章，主题不宜过多。
(3) 实践为主，理论大概讲一下
 研究理论的人毕竟是少数，技能类工具书以实践为主，以吸引更多读者，
(4) 多个作者保证同一风格。

2. 原创

 原创非常重要，在审稿时往往使用专门软件查重，千万不要大段摘抄。
(1) 不要直接使用别人写的示例。
(2) 不要使用无版权的图片。
(3) 不得不来源于网络的文字内容，换种说法，或者做成图。
(4) 对于自己在网上发布过的内容，需要证明是原创。如果被别人手快转载了，没办法确认发布的时间点前后，就悲剧了。（真有人做这样的工具，能在一分钟内转发到他自己的blog，还声明原创）。

3. 沟通

(1) 保持和编辑一致的Word版本。
(2) 修改编辑标注的内容时，改完不要删除标注，要在标注上注明“已修改”。
(3) 定稿后再修改或者修改编辑未列出自己发现的问题，需用颜色标出。

4. 排版

(1) 段落不超过五行。
(2) 一二级大小标题之间需要加入说明文字。
(3) 用不同字体标出注意事项，可多加入一些注意事项说明。
(4) 注意黑圈和小标题的区别：黑圈是并列符，当几句话没有前后关系可以调换位置时用黑圈，如果是步骤，或有前后顺序用小标题(1)(2)...
(5) 标题层次不宜过多，四级标题已经是极限，不要出现五级标题。四级以下可使用黑圈或小标题；或者标题上提，如将四级标题提成三级。
(6) 设置格式尽量用格式刷。
(7) 印刷一般不用Word排版，因此，尽量不使用自动编号。
(8) 链接地址不出现在正文中, 最好去掉未授权链接的具体地址。
(9) 尽量少写交叉引用，如“见3.4.5节”，否则修改章节号后非常麻烦。

5. 书写

(1) 英文
  i. 注意单词在前后文中大小写一致（如Python和python），并与官方保持一致。
  ii. 注意软件名与版本号之间的空格，如Python 3。
  iii. 注意专业英文不要拼错，比如Kaggle拼成Keggle，编辑可能看不出来，但读者能看出来。
  iv. 不要中英文混用，尽量用中文，没有中文名再用英文。
(2) 标点
  i. 注意冒号和句号使用，如“如图12.1所示。”。
  ii. 注意标点用中文标点（尤其是正文中的引号）。
  iii. 注意句末的标点。
(3) 习惯
  i. 注意通俗易懂和口语化的区别，尽量不使用“我”、“我们”、“这个”、“那个”，没用的词都去掉。
  ii. 注意笔者和编者的区别，不要在文中用错或者混用。

6. 图表

(1) 图片、代码、表格、公式出现前需要在正文中先引出，如“见公式2.1”
(2) 图片下方需要标号和描述，如“图1.1 计算机结构图”。
(3) 表格上方需要表头，如“表1.1 成绩数据表”。
(4) 公式之后需要加标号标号，如“（式2-1）”。
(5) 用自己做的图，不要加水印。
(6) 一般图片约占正文宽度的70%。
(7) 保证图像分辨率在300dpi及以上，同时注意图片上文字大小与版面的关系。
(8) 如果是黑白印刷，注意图表中的颜色，亮度相似的颜色可能看不出差别。
(9) 可多加一些流程图或者思维导图。

7. 代码

(1) 代码需要加行号。
(2) 代码注释平均三行一个。
(3) 文中注释尽量用中文
(4) 短注释尽量写在代码右侧。
(5) 删除不必要的空行。

 有一次，换了编辑，让我把之前文中所有的程序重加注释，达到平均三行一个注释，最好一行一个；正文不允许超过五行的段落……当时心里真的很不爽，也争论了半天：这么写注释是不是太low了？

 直到后来，再看到某本书，连续几页源码，没有行号，也没有注释，才觉得编辑小姐姐是对的，写代码和写文档偏重点不同。希望对大家有用。