如何写文档?

[nonocast]

很多年以来都很烦写注释和文档，其中一个观点是: 注释和文档都是因为代码烂，换句话说，如果代码可读性高，思路清晰就不需要注释和文档，你可以用好的变量名称或者Extract Method将方法名称来代替注释。

但是这两年在写javascript，也可能是因为弱类型的关系，有时候一个object可以直接穿越几个layer，你看着接口都不知道他从哪里来，他要去哪里，也越发觉得注释，文档和单元测试的重要性。

文档的类型从读者来说可以分为User和Developer， User可以理解为外部文档(External)，他们是交付物的消费者，消费者也有各种类型，前端人员要知道接口如何调用，测试人员要知道怎么测试，实施人员要知道怎么配置等等; 而Developer就可以理解为内部文档(Internal)，是写给开发团队看的，方便别人正确理解代码，有时候其实更多的时候是帮助自己回忆。

内部文档 (Internal)

• 产品需求 (PRD): 由项目经理编写，描述目标系统的业务功能
• 界面设计 (UI Proposal): 由交互设计人员编写，用PPT形式表达界面逻辑
• 设计文档 (Design): 由项目负责人编写，描写技术架构，业务模型，表达清楚如何组织即可
• 代码注释 (Comment): 由开发人员编写

外部文档 (External)

• 功能介绍 (Feature): 由项目负责人编写，写系统功能和特性
• 外部接口文档 (API Documentation): 由开发人员编写，后台服务就是描述HTTP API或者GraphQL API, 如果是前端webapp，这个应该就可以省略了
• 安装配置文档
• 测试文档

实践

Markdown

除了UI Proposal这种必须是slides形式，其他的文档建议有可能的情况下采用Markdown，主要是可以直接在IDE，如vscode中直接编辑，更为重要的是可以加进git作版本管理。

GraphQL API

GraphQL是自描述的，所以可以直接生成强类型文档，同时辅以docsify来作为补充，这个方式典型就是Github v4。

Restful API

说实话，Restful API描述也没有一个标准方法，Github v3, Office365, Slack, Zoom各有不同，其中Zoom对外公开了Swagger接口。大体上来说分为3种类型，

• 独立文档 (强类型): Swagger
• 独立文档 (弱类型): docsify
• 混合在代码文件中: apidoc

首先，放弃的就是apidoc这种类型，这种类型很尴尬，注释比代码还多，标准不如swagger这种规范，生成的页面不支持oauth调用，虽然是最方便的，但是质量不够。

Swagger的优势是足够强势，支持oauth直接调用，但是给你的空间不够多，需要花挺多时间去了解他，某种程度上变成了一个负担，随着接口增多文件巨长无比。vscode可以通过插件openapi缓解一下。

docsify就比较方便，只要规定一种格式，其他随便发挥，缺少调用，所以需要swagger或者postman辅助，但是其实测试调用还是用postman这种更为方便。

swagger和docsify本身都无法跟代码同步，所以需要靠开发团队重视。

写在最后

文档只是思考和实践的附属品，不能用文档代替思考和实践，千万不要为了文档而放弃思考和实践。