又是看 API 文档崩溃的一天

[richChou]

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

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

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

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

[memedahui]

支付宝我觉得是最好的,没有之一

[AoEiuV020]

程序员最讨厌的四件事：写注释，写文档，别人不写注释，别人不写文档

[huifer]

你可以写一个优质的文档让我们看看吗

[Tianao]

@huifer #3 同样是面向业务流程的，GitHub 的、Cloudflare 的就都很优质，不谢。

[freakxx]

天降正义：
所有事情都漂漂亮亮地处理好，就等着我按下关键的按钮。

[richChou]

@freakxx
@huifer
1. 文档的目的是产品服务给别人使用的时候，可以便捷地完成接入
2. 我们经常作为服务提供方、也是服务使用方，应该可以明白节省沟通成本是双赢的事情吧？
3. 一个合理且没有恶意的吐槽，如果你有不同的看法可以聊聊，这样冷嘲热讽挺没意思的

[qwertyzzz]

你可以写一个优质的文档让我们看看吗

[sprite82]

看楼上冷嘲热讽的，类似冰箱有问题我还得会制冷

[balabalaguguji]

请看优质的文档： https://easydoc.net/doc/30486560/ae8DEKDo/0wgri5M2

用易文档写接口文档很方便

[cmdOptionKana]

这个程序员的责任是次要，公司管理层负主要责任，要么对程序员写文档给予某种形式的奖励或鼓励，要么另外请专人写文档。不然写文档吃力不讨好，当然不爱写。

[zhengsidao]

有一说一，写接口文档国内真的是不太行
REST 参数名称 过去式 单复数都没有很好的遵守，可以看看谷歌的一些 API 接口信息，老外的 SaaS 服务为了保证对接一般都写的还可以....

[AoEiuV020]

@sprite82 别类似，你也是个冰箱，确实要会制冷，

[freakxx]

@richChou #6

> 3. 一个合理且没有恶意的吐槽，如果你有不同的看法可以聊聊，这样冷嘲热讽挺没意思的

还是挺有意思的。

比如我也可以说类似的话，
我们经常作为服务提供方、也是服务使用方，应该可以明白帮助别人改进也是双赢的事情吧？



这个事情，我只是觉得，你说这几家的文档烂嘛，已经做得挺不错的，说难用嘛，很多时候，历史遗留的问题，是留了很多坑坑挖挖；
只是很多时候，文档好不好用，在某些时候，变得不好用，这个是有部分主观的问题的；
这个事情是需要宽容一点的。

[freakxx]

@sprite82 #8

老实说，现在问题不是讨论冰箱能不能制冷的问题；
而是明知道冰箱千种万样，并且这个制冷不是每时每刻都是稳定的，也明知道保持这种稳定是很难的以至于基本不可能，还要求是这样，这样是很离谱的事；


就这个角度来说，你也是个冰箱，你能展示下 100%优质的制冷效果来看看？

[z54749412]

@memedahui 支付宝小程序不是抄的微信的？这么说就是微信比较牛批了么？

[z54749412]

@memedahui 少打了文档两个字，，非常抱歉

[freakxx]

@memedahui #1
@z54749412 #15

支付相关的文档，如果不限定的话，可以看下 stripe
接过几家的支付，接到 stripe，感觉是做得更舒服；

https://stripe.com/docs
https://stripe.com/docs/api

[InkAndBanner]

微信小商店的 api 也一样 文档仿佛是为了骗我而存在的

[AngryPanda]

@balabalaguguji 感觉美观上差了点意思

[raaaaaar]

我一直是很重视可读性，规范这种东西的，不过突然有一天有人跟我说注释写得太少。。

[tachikomachann]

ls 吐槽 lz 的原因应该是：你在抱怨国内文档写不好，但是没举个具体的例子，或者给出个写得好的范例。
不知道 lz 有没有做过技术客服。之前的工作做过这方面的工作一段时间，发现好的文档真的很难写，因为用户的水平参差不齐，知识背景不一样，对于同一段内容有些人就是觉得看不懂。当然还有部分原因是写文档的人本身对自己的产品是足够了解的，很难站在一个纯用户的角度组织语言。
所以我觉得很多时候光靠文档是不够的，训练有素的客服，氛围不错的社区都有助于提高沟通效率。

[WhiteDragon96]

1.没时间写，写文档的时间并不会算你工作时间
2.写好了也没人会表扬，写的差也没人说
3.能用就行

[mogg]

微信支付这文档已经做的不错了吧，把场景相关的都讲了一遍……
https://pay.weixin.qq.com/wiki/doc/api/micropay.php?chapter=1_1

[laduary]

@huifer 请参阅在线支付平台 Stripe 的文档： https://stripe.com/docs

[fiypig]

哈哈哈哈，一些第四方支付更扯，有些是真的简单，一些是数据类型不匹配，有些是神操作加密。

[cking]

@AoEiuV020 死循环 无解

[touchwithe]

AWS 的文档是真漂亮！此处特别点名批评阿里云。

[yin1999]

@touchwithe 移动云表示不服

[rabbitofyou]

你会发现无从改起 么有统一标准。。

[anguiao]

这种对外提供服务的 API 文档，和企业内部文档根本不能相提并论。这方面不知道楼上这些冷嘲热讽的是什么意思。
写文档确实是个技术活，这种用户很多的文档，应该有专门的人来负责，而不是靠程序员在写代码的时候随便写写。

[stevenhawking]

支付宝、微信支付、微信公众号、微信小程序的文档都是太屎之作。
大厂写出这种狗屎应该感到耻辱。

[israinbow]

我有写文档写注释写说明书的习惯,
但是也有代码写着写着忘了写上述内容的习惯,
最后就, 写了半俩的文档和断断续续的注释和有头无尾或者只有大纲和待办事项的说明书.
╮(╯▽╰)╭

[janxin]

目前国内还没接过比较好的 API 文档的例子，国外几个接的服务文档有几个还比较不错，但是也有一看就是开发自己糊了糊的。。。

[Lemeng]

文档都不喜欢写。呼吁也作用不大。除非有标准

[akira]

文档做的最好的应该是微软了吧，谷歌脸书的技术文档也很赞，
AWS 的技术文档灰常详细，但是普通人就是看不懂。。。

[JerryCha]

方案一天 3 变，早上做的东西指不定晚上就废弃。需求天天在变，快节奏赶需求的情况下很难产生高质量的文档。

[Huelse]

目前个人认为 rust 的文档最舒适，有兴趣的可以看看 https://doc.rust-lang.org/book/

[l12ab]

国内的，以前觉得 leancloud 的文档不错

[roundgis]

我曾經做過一段時間的所謂文檔工程師

就是單純幫開發組寫文檔

薪資也不高，當時大約 20k 港幣

公司要捨得花錢

[serverABCD]

@huifer 你别编程了，不适合这个行业

[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 的文档就很友好