又是看 API 文档崩溃的一天

[richChou]

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

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

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

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

[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 你别编程了，不适合这个行业