技术文档写做的道与术

• 世界观

  • 为何要写技术文档
  • 反驳不须要写文档的言论
  • 附议：为何要看文档
  • 什么算好的技术文档
  • 文档&写文档的定义

• 方法论

  • 基调

  • 结构

    • Introduction
    • Content
    • Terms
    • Setup
    • Body
    • Reference
    • FAQ
    • Appendix
    • ChangeLog
    • ReleaseNote
  • 过程

  • 工具

    • 写做工具
    • 维护工具
• 总结

![cover document
writing](https://github.com/vimerzhao/...

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

世界观

为何要写技术文档

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

某某同事的感谢.

![Snipaste 2019 12 19 20 57
10](https://github.com/vimerzhao/...

反驳不须要写文档的言论

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

附议：为何要看文档

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

1. 浪费开发时间
2. 开发没法随时答复，浪费本身时间
3. 信息没法固化、传承，并且过于琐碎，浪费团队时间

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

什么算好的技术文档

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

文档&写文档的定义

最后，我想探讨下写文档究竟是干嘛？百度百科说：

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

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

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

方法论

基调

在正式开始写文档以前，咱们必需要有如下三点认知：

1. 足够了解 ：
   咱们要为某个模块写文档，前提必定是咱们对这个模块足够了解，只有基于此，咱们的文档才是有价值的，不然只是信息垃圾。
2. 换位思考 ：
   即使有了交接文档，咱们也常常须要去询问交接人，这种状况家常便饭，究其本质，是由于不少时候咱们都是站在本身的角度、按照本身的理解来写文档的，可是读者的信息背景和咱们是彻底不同的，咱们以为理所固然的可能他们一无所知，因此写做文档必需要有足够的换位思考的意识。
   文档是写给别人看的，不是写给本身看的 。
3. MECE原则 ： 简单来讲就是 相互独立，彻底穷尽
   ，这个思想能够指导咱们对文档结构进行组织。下面给出一个参考。

结构

本章节讨论了一份技术文档应该具有的各个单元，能够做为从此技术文档写做的框架或者Checklist。

Introduction

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

![Snipaste 2019 12 19 21 14
12](https://github.com/vimerzhao/...

Content

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

![Snipaste 2019 12 19 21 17
04](https://github.com/vimerzhao/...

Terms

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

![Snipaste 2019 12 19 21 23
10](https://github.com/vimerzhao/...

Setup

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

![Snipaste 2019 12 19 21 25
33](https://github.com/vimerzhao/...

Body

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

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

对于具体的格式规范，推荐阅读 [ruanyf/document-style-guide:
中文技术文档的写做规范](https://github.com/ruanyf/doc...。

Reference

• 相关需求单：好比某个业务全部相关的需求单都放在这里，方便其余人更进一步了解背景，也方便本身查找。
• 参考资料。

这部分也能够放在附录里面，见下图。

FAQ

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

![Snipaste 2019 12 19 21 27
32](https://github.com/vimerzhao/...

Appendix

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

![Snipaste 2019 12 19 21 27
07](https://github.com/vimerzhao/...

ChangeLog

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

![Snipaste 2019 12 19 21 28
13](https://github.com/vimerzhao/...

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网页，编辑体验确定也比不上本地本身配置的编辑器。固然，术没有绝对的优劣之分，也要看本身是否合适。

总结

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