技术文档写作的道与术

• 世界观
  • 为什么要写技术文档
  • 反驳不需要写文档的言论
  • 附议：为什么要看文档
  • 什么算好的技术文档
  • 文档&写文档的定义
• 方法论
  • 基调
  • 结构
    • Introduction
    • Content
    • Terms
    • Setup
    • Body
    • Reference
    • FAQ
    • Appendix
    • ChangeLog
    • ReleaseNote
  • 过程
  • 工具
    • 写作工具
    • 维护工具
• 总结

文档的范围很广，本文特指 开发人员撰写的包含基本产品背景和主要技术设计的文档 。

世界观

为什么要写技术文档

对于这个问题，我个人觉得很容易回答，写技术文档可以帮助团队完成
当前的信息共享和长期的知识传承 。对于个人而言，一方面可以
节省时间 ，
因为避免了回答重复问题，也便于检索过去的知识；另一方面可以 塑造口碑
，比如某次就突然有个同事给我发消息说我的文档写的很好，对新接触这块业务的人帮助很大。

某某同事的感谢.

反驳不需要写文档的言论

有很多程序员都持有一个观点：“不用看(写)文档，文档都在代码里”，还有一部分人认为，文档容易过时，很难跟上代码的更新节奏，因而没有必要写文档。
凡此种种观点导致了一个局面就是：
接手业务的时候吐槽别人不写文档，交接业务的时候又觉得这东西无需解释，根本不需要文档
。
对此，首先我个人认为涉及代码细节的部分确实没必要写文档，但是对于总体的设计和业务的变更是绝对需要写文档的。有些人觉得文档有过时问题，那是因为他们没有引入版本（ChangeLog）的概念，
过时的文档本身就是业务历史的一部分
，我在接手一个业务的时候，常常就需要这些历史信息来辅助理解。

附议：为什么要看文档

上周发生了一件趣事，一个产品跟我说，
开发两句话能说明白的，为什么要看文档
？确实，问开发能以最快速度准确地获取信息，毕竟人脑就是一个强大的搜索引擎。但是长期来看有以下问题：

1. 浪费开发时间

2. 开发无法随时答复，浪费自己时间

3. 信息无法固化、传承，而且过于琐碎，浪费团队时间

一般来说，一份 好的技术文档
比起开发口述是不会有多余的理解成本的，甚至更低，因为对于很多信息，图片能比语言更好地表达。

什么算好的技术文档

我认为 好的技术文档 的核心是 敏捷 。一方面，好的的技术文档是
高度可维护的并且经常维护
的，比如新增了一些功能，文档的作者能够快速更新文档，文档的读者能及时获取更新；另一方面，好的技术文档是
易理解 的，更详细来说要表述准确、结构清晰、排版美观、风格统一。

文档&写文档的定义

最后，我想探讨下写文档到底是干吗？百度百科说：

软件文档或者源代码文档是指与软件系统及其软件工程过程有关联的文本实体。

那么写文档就是生产这个实体的过程了。但这样实在过于抽象，根据我最近一年的经验来看，我更愿意将其定义为
对特定信息进行结构化整理的过程 。

以上就是写作技术文档的道了，也就是我们对于这件事最基础的世界观，接下来谈术，即基于此执行的方法论。

方法论

基调

在正式开始写文档之前，我们必须要有以下三点认知：

1. 足够了解 ：
   我们要为某个模块写文档，前提一定是我们对这个模块足够了解，只有基于此，我们的文档才是有价值的，否则只是信息垃圾。

2. 换位思考 ：
   即便有了交接文档，我们也经常需要去询问交接人，这种情况屡见不鲜，究其本质，是因为很多时候我们都是站在自己的角度、按照自己的理解来写文档的，但是读者的信息背景和我们是完全不一样的，我们觉得理所当然的可能他们一无所知，所以写作文档必须要有足够的换位思考的意识。
   文档是写给别人看的，不是写给自己看的 。

3. MECE原则 ： 简单来说就是 相互独立，完全穷尽
   ，这个思想可以指导我们对文档结构进行组织。下面给出一个参考。

结构

本章节讨论了一份技术文档应该具备的各个单元，可以作为今后技术文档写作的框架或者Checklist。

Introduction

简单介绍项目背景信息，如下面是我为某个项目写的 Introduction ：

Content

目录，目录是结构的直接体现，必须有，一般文档写作工具都能自动生成：

Terms

术语解释，很多业务会衍生一些特定词汇，如“白条卡”、“大图卡”等，都是有特定语境的，需要单独解释。

Setup

如何运行这个项目，一般开源项目都会有，如果是SDK文档也常常有接入文档，就是这个模块。

Body

这部分就是文档的主体部分，具体结构需要视内容而定，有以下通用规则

• 一图胜千言，如Android的架构图、Actvity的生命周期图，比任何语言都好使。

• Demo胜千言。

对于具体的格式规范，推荐阅读 ruanyf/document-style-guide:
中文技术文档的写作规范。

Reference

• 相关需求单：比如某个业务所有相关的需求单都放在这里，方便其他人更进一步了解背景，也方便自己查找。

• 参考资料。

这部分也可以放在附录里面，见下图。

FAQ

其他人经常问的问题，遇到就记录在这个模块，不断补充，日趋完善。

Appendix

一些比较冗长的信息可以放在附录里面，比如日志，避免放在正文影响排版和阅读。

ChangeLog

变更日志，一般开源项目都会记录每个版本的重要变更。

ReleaseNote

发版日志，一般开源项目都会有一个单独的Release页面。

过程

一般来说，文档写作的流程如下：
收集信息、整理框架、实践结论、写作文档
。如果前期工作足够，写作所花的时间是很少的。
此外，文档完成后，还要注意读者反馈，以不断完善自己的文档。
写一份好的技术文档也不是一蹴而就的，需要不断打磨，要注意经常去
刻意练习 。

工具

写作工具

一般来说，只要别人发给我的文档是一份Word文档，我基本就把这份文档排在了最LowB的一档。对于这种文档，我就想问两点：

• 文档有更新怎么分发给每个需要这份文档的人？

• Word格式不兼容导致关键图表排版混乱怎么办？

一般来说，文档写作工具有以下选择：

• Word

• Pdf

• Markdown

• Asciidoc

• Latex

对于Word/Pdf我是极力排斥的，因为很多文档都是需要更新的，这两种格式没法做到
动态更新 。Markdown
比较受开源社区的欢迎，因为它在表达力和简洁性之间找到了一个平衡点，但是它有一个致命问题就是
无法应付稍微复杂一点的排版
。Asciidoc是我的主力文档工具，很多人不知道Github也是支持这种文档格式的，比如本文就是这种格式的。Asciidoc的语法比Markdown更加复杂，但我认为
牺牲一点时间学习是完全值得的
。最后是Latex，Tex的变种，表达力最强大，可以应付各种复杂排版，一般在学术圈比较流行（尤其是那些复杂数学公式的表达），但我认为放在日常的文档写作中有点矫枉过正了。
综上，我推荐Asciidoc。

维护工具

对于文档的管理，我推荐使用Git，像管理代码一样管理文档。
另外我推荐使用一个静态网站来存放自己的文档，这样其他同事访问的时候看到的总是最新的文档了。
另外，公司目前在推iWiki，我觉得iWiki最大的优势是 权限控制
，对于一些敏感文档是必须的。但是，比起iWiki的变更记录，作为程序员的我更钟爱用Git进行管理，此外，iWiki是Web网页，编辑体验肯定也比不上本地自己配置的编辑器。当然，术没有绝对的优劣之分，也要看自己是否合适。

总结

以上，最近关于技术文档写作的一些思考。欢迎交流指正。