又是看 API 文档崩溃的一天

[richChou]

从业多年几乎没看到过一份合格的 API 文档。

回想了一下，接触比较多的什么京东开普勒、微信开放平台、支付宝，以及各种提供开发平台服务的小公司，就没有几个省心的文档。

包括不限于 无业务整体流程、文档结构不清晰、参数命名规则混乱、参数说明含糊不清、示例与说明不一致、出现未说明错误码 等问题。

拜托各位业务负责人、各个 Leader 、还有写文档的铁子们，写文档的时候稍微多花点心思，节约大家的沟通成本。皆大欢喜不好吗？

[acmore]

支持楼主的观点。
这跟你是不是冰箱没有关系，不管你是个啥，面前这个冰箱不制冷那就是不好的，就是应该被吐槽的。
你自己不制冷是另一回事，楼上某些人不必偷换概念。

[iyaozhen]

之前项目有一版的接口文档是我参与写的（我是 QA ）。

直接说结论：没有收益

要想写好文档非常的难，需要考虑很多场景（不止是列出参数，还得教被人怎么用，写各个语言的示例代码），翻很多代码（即使多人协作，总得有人 review 全部的），还需要保持更新。而且一般的同学还写不了，还得高工写，这样的话又耗时间又没收益。

[mxT52CRuqR6o5]

写好文档有 roi 吗，反正我都垄断了，你不用也得用

[namelosw]

Stripe / Twilio 的 API 最好，文档也很不错。

文档好不好主要取决于公司和团队的 mindset：
1. 不好的公司和团队：文档就是累赘，开发完了，写文档就是顺便应付鬼子。个人想写好只能硬挤时间完善，对 performance 完全没有帮助。
2. 好的公司和团队：一个功能没有文档 = 这个功能不存在。一个功能没有好的文档，等于任务只完成了一半。优化文档是每个人职责的重要组成部分，因此也会影响 performance 。

还有一些团队文档驱动开发，先把文档迭代到自己真的会爱用的程度再去实现。

[levelworm]

写需求，写文档，都是吃力不讨好但是长远看比较重要的两件事情。所以这事情还是得公司或者组给力。
不过互联网风、业务驱动的公司我觉得可能都没时间，一切从快。。。外加业务话语权最大可以随便换需求，换来换去需求文档都变成屎了。

[levelworm]

@namelosw 文档驱动开发我觉得蛮好的，搞得好的话，弄不好可以半自动化。当然前提是需求搞清楚，框架搭起来。

[xarthur]

我一直觉得接口文档之类的其实需要直接从代码和注释里生成。

[dayeye2006199]

拿手写文档的基本不成。得根据注释、类型之类的信息直接从代码里面生成出来，才能保证不断更新。

[ragnaroks]

文档天花板 --MSDN

[yikyo]

印象中微信有个文档 字段的大小写错了，导致报错，还找不到原因。

[sleepm]

又不是不能用
不过话说回来，文档一直是变化最慢的

[lovecy]

你想要的写得好的文档，是你自己看得舒服的哪种，说不定另一个人来看又不舒服了。
这东西貌似也没有大家都认可的规范啥的，我一直觉得只要不遗漏重要的点就算好文档了。。

[lovecy]

@iyaozhen 而且就算有一份非常详细的文档，也没法避免伸手党问这问那的

[zxcslove]

冷嘲热讽的渣渣真是可耻

[Stain5]

@AoEiuV020 准确来说是看公司价值观吧

写文档轻松 不用掉头发

如果工期宽长 有有人认可的话

[byron]

支付宝文档有捉虫奖励。

包括楼主说的错别字、功能缺失、内容缺失、demo 示例错误、流程无法跑通、上下文描述不一致、内容错误、错误的超链接、产品类错误 等。
捉虫范围
开放平台文档中心： https://openhome.alipay.com/docCenter/docCenter.htm
主要模块包括：
• 小程序
• 网页&移动应用
• 生活号
• 第三方应用
• IoT
• 插件

活动地址： https://forum.alipay.com/mini-app/post/41201012?from=opendocs-activity

[hotsymbol]

AWS，Azure，Google Cloud 的文档就很友好