干货｜关于文档书写的一些想法

点击上方“中兴开发者社区”，关注我们

每天读一篇一线开发者原创好文

▍作者简介

作者谢伟是一名开源软件爱好者，在工作中学习总结是他的习惯。本文主要针对程序员如何编写一篇合格的文档，提供一些思路，希望对大家有所启发。

写出的文档如何能更容易理解和操作？

编写一份文档，为达到容易理解和操作的程度，需要对大量的语言重新组织，内容的不同呈现，借助辅助工具等一系列操作，本文是对工作中所写文档的部分总结，以个人视角剖析文档写作的全流程，大家对文档写作有什么想法也欢迎在评论中探讨。

下面我将按照：

编写文档的准备工作-根据现有文档搭建问题-语言的组织和呈现-文档输出 

这一顺序展开叙述。

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

程序员在工作中会接触到各式各样的技术文档，文档写的好与不好，大致都能区分出来。

奇怪的是，一方面，许多程序员对技术、代码可以修改、修改、再修改，优化、优化、再优化，......，追求完美的天性发挥的淋漓尽致，另一方面，对于自己写的文档却可以容忍 “混乱” 、“难以理解”等......

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

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

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

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

▍1. 什么是好的文档？

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

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

比如个人最崇拜的世界 Python 技术排名第五的作者： kennethreitz，他的开源作品：requests，再比如：开源 web 框架 Django，这两个项目的文档堪称是教科书式文档示例。

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

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

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

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

我现在的步骤是：

• 收集

• 梳理

• 实践

• 编写

• 
  

• 
  

2.1 收集

收集现有的资料，以及相关故障的问题记录文档（其中已知的故障问题文档很重要，这能让你明白别人问题会出现在哪）

和原文档编写者沟通（也能让你感性的认识到他口中的文档的问题）

• 
  

2.2 梳理

根据收集的到的资料，感性的认识到文档的整体流程是什么，以及需要注意些什么

记录：把已知问题进行记录

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

2.3 实践

根据收集的资料和现有的文档进行操作

注意你的出错的点，以及你根据别人的提示避开的出错的点

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

2.4 编写

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

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

• 逻辑表达、内容组织

• 排版
  

▍3.如何进行排版？

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

标题    文本     段落     图片     表格

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

阮一峰：中文技术文档写作规范（点击文末阅读原文查看）

标题：

标题原则上存在六级，即一级、二级、三级、四级、五级和六级标题。但这里我推荐使用前三级标题，其余的使用列表项目进行组织。因为层级组织多了，其实并不太友好：不仅达不到分类，似逻辑清晰的目的，还容易造成读者混乱。其实是并不太友好。

文本：

参考示例中讲了很多，需特别注意三点：

1.重点强调使用加粗处理，且重点强调的不应过长。比如你强调了几百个字符，其实相当于没起到强调的作用

2.注意中英文的处理：即英文和中文强化空一格。比如：English 英语

3.慎用斜体

段落：

各段落中间使用换行处理。

一个段落不应过长，尝试拆分成几个段落。

图片：

图片的作用：即对一些文字不好描述的使用图片视觉化呈现

图片的大小：文档内的图片建议大小一致：即宽度和网页同宽度；达不到需求的建议居中处理。

表格：

我谈论一点：

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

其他：注意整体风格。

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

流程化：1. 先有什么 2. 后有什么 3. 最后结果

精细化：逻辑表达、内容组织、排版