Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

如何写文档? #9

Open
nonocast opened this issue Mar 2, 2020 · 0 comments
Open

如何写文档? #9

nonocast opened this issue Mar 2, 2020 · 0 comments

Comments

@nonocast
Copy link
Owner

@nonocast nonocast commented Mar 2, 2020

很多年以来都很烦写注释和文档,其中一个观点是: 注释和文档都是因为代码烂,换句话说,如果代码可读性高,思路清晰就不需要注释和文档,你可以用好的变量名称或者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本身都无法跟代码同步,所以需要靠开发团队重视。

写在最后

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
1 participant
You can’t perform that action at this time.