如何写出优秀的技术文档？

大家好，我是小枣君。

鲜枣课堂自从2017年5月开始正式创立，迄今已有3年多的时间。这一期间，我们的内容一直都坚持以技术类科普文章为主，输出了大约400多篇原创。其中绝大部分，都是我写的。

我的想法比较简单，就是希望能够输出通俗易懂的技术科普文章，让技术不再枯燥，帮助更多人（尤其是即将进入行业的年轻人）了解通信，了解5G、物联网、云计算和大数据这样的ICT领域前沿科技知识。

非常庆幸的是，鲜枣课堂的内容受到了大家的欢迎，得到了宝贵的认可，也积累了越来越大的影响力。我们现在已经逐渐成为行业里排名前列的技术类内容原创自媒体。

其实，我之所以会选择技术文章写作这条路，和我的个人经历是分不开的。

我曾经在某设备商做了四年的技术支持（其中三年海外），积累了丰富的通信产品技术知识和实践经验。然后，又做了三年的文档经理，积累了大量的文档写作、文档体系建设、文档质量管理方面的经验。最后，又做了四五年的培训经理，学习如何进行高效的内容表达、如何针对内外部客户进行知识传递。

多元化的职场经历，为我创办鲜枣课堂贡献了知识背景和能力基础。

尤其是技术文档写作这一块，我从刚入职就养成了经验随手总结、技术定期积累的日常写作习惯，并保持至今，可以说是受益匪浅。

文档，不管是对于员工个人，还是对于企业，都有非常重要的意义。对于技术类公司来说，技术文档的重要性更是不言而喻。它的价值，完全可以等同于产品本身。或者说，技术文档就是产品的一个重要组成部分。

很多人认为文档是产品的附属品，是例行公事的印刷品，这显然是不对的。

文档的根本性质，是贯穿产品生命周期的沉淀积累输出物，是信息传递的重要工具和载体。不同阶段的文档，有不同的作用。不同的岗位，有不同的文档体系。

在产品设计和研发阶段，有产品设计指导书、产品功能需求说明书等。在产品工程交付阶段，有版本发布说明、技术指导书、升级/割接/扩容指导书等。

产品文档体系的范例

文档还分为内部文档和外部文档。内部文档服务于内部用户，外部文档服务于客户、合作方等外部用户。内外部文档密级不同，内容会有所删减，表述方式和侧重点也会有所不同。

文档用于指导实际工作。文档质量的好坏，会影响信息传递的准确性和效率，进而影响工作的完成、项目的交付。

例如，产品开通文档太烂，客户看不懂，合作方员工看不懂，甚至自己的工程师也看不懂，就无法依照文档成功完成设备开通或升级割接。文档如果出现错误，甚至可能造成严重的事故。

现在市场竞争越来越激烈。有时候，虽然产品本身做得很好，价格也很有优势，但是文档太烂，一样会被客户鄙视，进而拉低了产品的整体竞争力。有损公司品牌形象。

那么，决定产品文档质量的基本要素是什么呢？

有人说，是作者的写作水平。也有人说，是是否有充足的时间。

其实都不对，基本要素只有一个，那就是钱。

文档写作是一个需要投入大量资源的工作。

首先，需要建立一个完善的文档管理体系，包括文档架构体系，文档职责归属，文档立项、开发、评审、发布、归档流程以及对应平台等。

其次，需要安排大量的专任或兼任岗位跟进相关流程管理，占用工时。

再有，文档和产品开发一样，是一个滚动性流程，需要不断更新迭代。所以，资源投入也是持续性的。

早期的时候，国内很多企业利用人力成本优势，发起人海战术，将资源集中投入到产品研发上，靠价格优势和版本速度（需求响应速度）抢占市场。

开发工程师忙着写代码，做版本，哪有时间去写文档？基本上都是拿产品设计指导书改一改，截截图，就扔给了售后，甚至扔给了客户。

内部用户（售后）骂娘，领导其实心里有数，毕竟资源有限，只能牺牲文档保版本，对内部反馈进行弹压。而外部客户的意见，是无法进行弹压的。

对于一些低端客户来说，比较关注的是价格。极端的成本优势，可以让客户忽视文档。但是，对于高端用户来说，他们对文档的要求和对产品的要求是一致的。没有优秀齐套的文档，一样不给中标。

于是，倒逼设备商投入资源补齐短板，组织人力进行文档专项开发。结果发现，其实并不是写不出好文档，而是之前没有舍得投入资源。

然而，一旦项目应付过去，资源又会撤走，好不容易建立起来的文档质量，又再次垮塌，如此恶性循环。

所以说，对于企业，想要把文档满意度搞好，树立有利于产品品牌的文档品牌形象，关键在于领导愿不愿意投钱。有钱就有人有资源，这是搞好文档的基本前提。

随着市场的规范和成熟，加上竞争日趋激烈，文档的重要性不断提升，越来越多的企业负责人开始意识到这个问题，不断加大对文档的资源投入。

战略层面的重视是基础，战术层面的执行是关键。

前面说的文档管理体系，是有一整套方法论的。大到文档体系的架构（到底需要多少篇文档，分别由谁来负责，写给谁看），小到文档内容的编写，都有相应的理论和技巧。这些不是靠人海战术就可以完美完成的。

限于篇幅，我就不详细介绍文档管理体系了。我重点说说单篇文档的写作技巧。

想要写好一篇文档，首先第一个问题，就是你要搞清楚这篇文档的定位——它是一篇什么性质的文档？写作目的是什么？它的使用者是谁？

文档的定位，直接决定了整篇文档的基调。

例如我经常写的零基础入门，定位就是对相关内容背景知识毫无了解的读者。然而，又不是小学生那种层次，而是至少已经完成了基础教育，处于大一及以上学历水平的读者，有基本的物理学和数学常识，也有对自然现场的基本认知，还有正常人的逻辑思维能力。

如果你写技术文档，首先要搞明白，文档使用者是内部客户还是外部客户，是有经验的客户，还是零基础的客户，是已经阅读过前置文档的客户，还是第一次看这套文档的客户。

明确了对象之后，要切记，在写作整篇文档的过程中，你都要随时切换自身角色。一定要站在读者的角度，琢磨文档内容是不是能看得懂。

如果没有把握，那么，就找个和目标读者处于同等水平的体验用户，让他试读，提供反馈意见。

大部分技术文档的作者不是作家，甚至不是文科生，而是技术工程师。这类人在文字表达技巧上通常比较欠缺，但是有一个显著优势，那就是逻辑思维能力强。对于写作来说，这一点非常重要。尤其是技术文档的写作，必须有很强的逻辑思维能力。

文档的总体结构，必须要有逻辑连贯的章节顺序。文档的语句，也必须有逻辑严谨的表述方式。过于跳跃的思维，不适合应用于技术类文档。文科生过于感性的文字，也不适合技术类文档。

技术工程师最常犯的毛病，就是自以为是：“这么简单，你怎么都不懂？”“这是基础啊，是个人都懂！”然后就偷工减料，言简意赅，跳过了大量的细节，忽视了可能出现的不同情况，让文档使用者不知所措。甚至有的作者，喜欢玩“玄学”，觉得越写得高深，就越显得自己很懂，简直可笑。

规范的技术文档，通常会遵循SOP的原则。所谓SOP，就是 Standard Operating Procedure，标准作业程序。

下面这段内容，是一个SOP文档写作的范例：

大家会看到，前置信息非常充分，该介绍的背景，都会介绍到位。

具体的操作步骤，虽然简短，但内容十分清晰，分为几个步骤，每一个步骤敲什么命令、有什么目的，都会告诉你。

在最后，还会有验证结果环节（本例的验证结果部分相对简略，实际上还应该包括通过命令，查看结果，以此进行明确验证）。

上面这种SOP的文档写作方式，和我们从小接受过的传统写作是完全不同的，

以前我们常说，中式菜谱喜欢用“盐少许、酱油少许、大火煎炸片刻”这种定量非常模糊的表达方式，其实确实和我们的写作习惯有一定关系。对于技术文档来说，我们这方面的偏重性培养和训练确实做得不够。真正的写作，不是刻意追求辞藻的华丽，而是意思和情境的准确表达。

要想写好技术文档，还有一个重要技巧，那就是多用图表。

所谓“字不如表、表不如图”。技术是很抽象的东西，也是理解起来很有难度的东西。想要靠纯文字进行内容转述，是很困难的。所以，应该更多地借助表格和图片，甚至gif动图，帮助读者理解。

说白了，这个就是考验作者的责任心。如果写作者不能站在读者的角度，不能以读者满意度为出发点，那么，就不会愿意多此一举去画图。画图是很复杂的工作，有时候我写文章，一幅图都要画一天，很不容易。

技术文档的写作，不仅对企业来说非常重要，对于个人来说，也是受益匪浅的。

养成并坚持写作的习惯，有利于培养逻辑思维能力，也有利于个人知识沉淀积累。个人可以开技术blog或公众号，发表并分享自己的经验心得，会很有成就感，日积月累的话，甚至可能形成个人品牌和影响力，有利于自己的职业生涯发展。

虽然现在视频化的趋势明显，但是我个人认为，文档是无法被视频取代的。目前的技术，视频无法进行快速内容检索，无法进行快速更新和修改，无法进行快速传递，文件体积较大，这些都决定了文档的不可替代性。

视频的优势，更多在于内容形象而生动的展示，可以让用户有更感性的认识，更深刻的记忆，适合培训，不适合工作查阅，不适合归档。

好啦，以上就是小枣君关于技术文档写作的分享，希望对大家有所帮助。顺便打个小广告，大家如果有自己觉得还不错的技术文档输出，也欢迎投稿给鲜枣课堂，稿酬丰厚！

最后，感谢大家的耐心阅读，我们下期再见啦！

—— The End ——