技术文档如何编写？

关于文档编写的几个思维

近期重新组织了好几篇技术文档，把其中的一些感悟提炼出来。

文档为达到容易理解和操作的程度，对大量的语言重新组织，内容的不同呈现，借助辅助工具等一系列操作，本文就是剖析整个流程

全文主要的流程是：

• 编写文档前，准备工作有哪些？
• 根据现有文档的问题是？
• 语言的组织和内容的不同呈现方式有哪些？
• 按照现有文档完成后的文档输出如何组织？

0. 程序员如何看待文档？

程序员一定会是接触各种各样的技术文档，文档写的好与不好，大致都能区分出来。

但是对于自己写的文档却可以容忍 “丑陋” 、“难以理解”等......

对技术、代码可以修改、修改、再修改，优化、优化、再优化......

我觉得出现问题在于：程序员对于如何有效的逻辑表达以及优秀的排版没有意识。

据我观察，一个程序员完成了一份代码的编写，对文档只会花小部分时间进行书写，会自然而然的忽略部分信息，认为把信息堆砌出去，就是一篇文档......

不不不，我认为不应该这样......

但凡伟大的公司、产品对“呈现” 这一块都绝对的重视。尽量都在简化用户的操作复杂程度，比如极度克制的微信。

1. 什么是好的文档？

如何定义一份文档是通俗意义上的好？

就个人的认识，可以从 GitHub 上的最热门的开源项目的文档入手？

比如个人最崇拜的世界 Python 技术排名第五的作者： kennethreitz，他的开源作品：requests

再比如：开源 web 框架 Django

这两个项目的文档堪称是教科书式文档示例。

阅读这些项目的文档，一定有个感官的认识：文档写的好，根据文档能使用起来，整体文档的风格也高度的统一。

一个好的文档我认为具有下面三个特点：准确、清晰和美观

准确和清晰对应逻辑梳理和表达。
美观对应排版。

pic_1.png

2. 编写文档的整体流程有哪些？

我现在的步骤是：

• 收集
• 梳理
• 实践
• 编写

2.1 收集

• 根据 wiki 收集现有的资料，以及相关故障的问题记录文档（其中已知的故障问题文档很重要，这能让你明白别人问题会出现在哪）
• 和原文档编写者沟通（也能让你感性的认识到他口中的文档的问题）

2.2 梳理

• 根据收集的到的资料，感性的认识到文档的整体流程是什么，以及需要注意些什么
• 记录：把已知问题进行记录

梳理环节主要是关注现有文档的整体流程以及你如何可以对现有流程优化

2.3 实践

• 根据收集的资料和现有的文档进行操作
• 注意你的出错的点，以及你根据别人的提示避开的出错的点

实践环节主要是关注那些 ‘坑’，直到你成功的按照步骤得到理想的结果

2.4 编写

现在手头你已经有历史经验（收集的资料）和 实践经验（实践环节）。

进行文档的编写需要注意两个点：

• 逻辑表达、内容组织
• 排版

一篇文档主要包含这些内容：

• 标题
• 文本
• 段落
• 图片
• 表格

pic_2.png

这里有一篇中文技术文档写作规范参考：阮一峰：中文技术文档写作规范

标题：

我只谈论一点：标题原则上存在六级，即一级、二级、三级、四级、五级和六级标题。但我推荐使用前三级标题，其余的使用列表项目进行组织。因为层级组织多了，其实是并不太友好。

文本：

参考示例中讲了很多，我值谈论三点：

• 重点强调使用加粗处理，且重点强调的不应过长。比如你强调了几百个字符，其实相当于没起到强调的作用
• 注意中英文的处理：即英文和中文强化空一格。比如：English 英语
• 慎用斜体

段落：

我谈论一点：

• 各段落中间使用换行处理。
• 一个段落不应过长，尝试拆分成几个段落。

图片：

我谈论两点：

• 图片的作用：即对一些文字不好描述的使用图片视觉化呈现
• 图片的大小：文档内的图片建议大小一致：即宽度和网页同宽度；达不到需求的建议居中处理。

表格：

我谈论一点：

• 表格的作用：对内容的分类和组织，能用表格表达比文字好。

其他：注意整体风格。

综上：编写文档的两个思维是：

• 流程化：1. 先有什么 2. 后有什么 3. 最后结果
• 精细化：逻辑表达、内容组织、排版

pic_3.png