这是一个创建于 1266 天前的主题，其中的信息可能已经有所发展或是发生改变。
从业多年几乎没看到过一份合格的 API 文档。
回想了一下，接触比较多的什么京东开普勒、微信开放平台、支付宝，以及各种提供开发平台服务的小公司，就没有几个省心的文档。
包括不限于 无业务整体流程、文档结构不清晰、参数命名规则混乱、参数说明含糊不清、示例与说明不一致、出现未说明错误码 等问题。
拜托各位业务负责人、各个 Leader 、还有写文档的铁子们，写文档的时候稍微多花点心思，节约大家的沟通成本。皆大欢喜不好吗？
回想了一下，接触比较多的什么京东开普勒、微信开放平台、支付宝，以及各种提供开发平台服务的小公司，就没有几个省心的文档。
包括不限于 无业务整体流程、文档结构不清晰、参数命名规则混乱、参数说明含糊不清、示例与说明不一致、出现未说明错误码 等问题。
拜托各位业务负责人、各个 Leader 、还有写文档的铁子们，写文档的时候稍微多花点心思，节约大家的沟通成本。皆大欢喜不好吗？
 |
1
memedahui 2021-06-04 15:28:41 +08:00
支付宝我觉得是最好的,没有之一
|
 |
2
AoEiuV020 2021-06-04 15:29:30 +08:00  22
程序员最讨厌的四件事：写注释，写文档，别人不写注释，别人不写文档
|
 |
3
huifer 2021-06-04 15:30:28 +08:00 6
你可以写一个优质的文档让我们看看吗
|
 |
5
freakxx 2021-06-04 15:41:22 +08:00
天降正义：
所有事情都漂漂亮亮地处理好，就等着我按下关键的按钮。 |
 |
6
richChou OP 11
|
 |
7
qwertyzzz 2021-06-04 16:00:52 +08:00
你可以写一个优质的文档让我们看看吗
|
 |
8
sprite82 2021-06-04 16:09:43 +08:00 8
看楼上冷嘲热讽的，类似冰箱有问题我还得会制冷
|
 |
9
balabalaguguji 2021-06-04 16:10:35 +08:00 1
|
 |
10
cmdOptionKana 2021-06-04 16:20:26 +08:00
这个程序员的责任是次要，公司管理层负主要责任，要么对程序员写文档给予某种形式的奖励或鼓励，要么另外请专人写文档。不然写文档吃力不讨好，当然不爱写。
|
 |
11
zhengsidao 2021-06-04 16:25:13 +08:00
有一说一，写接口文档国内真的是不太行
REST 参数名称 过去式 单复数都没有很好的遵守，可以看看谷歌的一些 API 接口信息，老外的 SaaS 服务为了保证对接一般都写的还可以.... |
|
13
freakxx 2021-06-04 16:44:26 +08:00 1
@richChou #6
> 3. 一个合理且没有恶意的吐槽，如果你有不同的看法可以聊聊，这样冷嘲热讽挺没意思的 还是挺有意思的。 比如我也可以说类似的话， 我们经常作为服务提供方、也是服务使用方，应该可以明白帮助别人改进也是双赢的事情吧？ 这个事情，我只是觉得，你说这几家的文档烂嘛，已经做得挺不错的，说难用嘛，很多时候，历史遗留的问题，是留了很多坑坑挖挖； 只是很多时候，文档好不好用，在某些时候，变得不好用，这个是有部分主观的问题的； 这个事情是需要宽容一点的。 |
|
14
freakxx 2021-06-04 16:48:28 +08:00
@sprite82 #8
老实说，现在问题不是讨论冰箱能不能制冷的问题； 而是明知道冰箱千种万样，并且这个制冷不是每时每刻都是稳定的，也明知道保持这种稳定是很难的以至于基本不可能，还要求是这样，这样是很离谱的事； 就这个角度来说，你也是个冰箱，你能展示下 100%优质的制冷效果来看看？ |
|
17
freakxx 2021-06-04 16:57:43 +08:00
@memedahui #1
@z54749412 #15 支付相关的文档，如果不限定的话，可以看下 stripe 接过几家的支付，接到 stripe，感觉是做得更舒服； https://stripe.com/docs https://stripe.com/docs/api |
 |
18
InkAndBanner 2021-06-04 17:51:48 +08:00 1
微信小商店的 api 也一样 文档仿佛是为了骗我而存在的
|
 |
19
AngryPanda 2021-06-04 18:05:18 +08:00
@balabalaguguji 感觉美观上差了点意思
|
 |
20
raaaaaar 2021-06-04 18:07:35 +08:00 via Android
我一直是很重视可读性，规范这种东西的，不过突然有一天有人跟我说注释写得太少。。
|
 |
21
tachikomachann 2021-06-04 18:07:51 +08:00 via Android 4
ls 吐槽 lz 的原因应该是：你在抱怨国内文档写不好，但是没举个具体的例子，或者给出个写得好的范例。
不知道 lz 有没有做过技术客服。之前的工作做过这方面的工作一段时间，发现好的文档真的很难写，因为用户的水平参差不齐，知识背景不一样，对于同一段内容有些人就是觉得看不懂。当然还有部分原因是写文档的人本身对自己的产品是足够了解的，很难站在一个纯用户的角度组织语言。 所以我觉得很多时候光靠文档是不够的，训练有素的客服，氛围不错的社区都有助于提高沟通效率。 |
 |
22
WhiteDragon96 2021-06-04 18:13:20 +08:00
1.没时间写，写文档的时间并不会算你工作时间
2.写好了也没人会表扬，写的差也没人说 3.能用就行 |
 |
23
mogg 2021-06-04 18:28:16 +08:00
微信支付这文档已经做的不错了吧，把场景相关的都讲了一遍……
https://pay.weixin.qq.com/wiki/doc/api/micropay.php?chapter=1_1 |
 |
24
laduary 2021-06-04 18:42:49 +08:00
@huifer 请参阅在线支付平台 Stripe 的文档： https://stripe.com/docs
|
 |
25
fiypig 2021-06-04 18:46:05 +08:00 via iPhone
哈哈哈哈，一些第四方支付更扯，有些是真的简单，一些是数据类型不匹配，有些是神操作加密。
|
 |
27
touchwithe 2021-06-04 21:16:11 +08:00 via iPhone
AWS 的文档是真漂亮！此处特别点名批评阿里云。
|
 |
28
yin1999 2021-06-04 21:50:04 +08:00
@touchwithe 移动云表示不服
|
 |
29
rabbitofyou 2021-06-04 21:51:47 +08:00
你会发现无从改起 么有统一标准。。
|
 |
30
anguiao 2021-06-04 21:55:44 +08:00 via Android 1
这种对外提供服务的 API 文档，和企业内部文档根本不能相提并论。这方面不知道楼上这些冷嘲热讽的是什么意思。
写文档确实是个技术活，这种用户很多的文档，应该有专门的人来负责，而不是靠程序员在写代码的时候随便写写。 |
 |
31
stevenhawking 2021-06-04 22:12:37 +08:00
支付宝、微信支付、微信公众号、微信小程序的文档都是太屎之作。
大厂写出这种狗屎应该感到耻辱。 |
 |
32
israinbow 2021-06-04 22:17:46 +08:00
我有写文档写注释写说明书的习惯,
但是也有代码写着写着忘了写上述内容的习惯, 最后就, 写了半俩的文档和断断续续的注释和有头无尾或者只有大纲和待办事项的说明书. ╮(╯▽╰)╭ |
 |
33
janxin 2021-06-04 22:49:39 +08:00
目前国内还没接过比较好的 API 文档的例子，国外几个接的服务文档有几个还比较不错，但是也有一看就是开发自己糊了糊的。。。
|
 |
34
Lemeng 2021-06-04 23:07:34 +08:00
文档都不喜欢写。呼吁也作用不大。除非有标准
|
 |
35
akira 2021-06-04 23:10:30 +08:00
文档做的最好的应该是微软了吧，谷歌脸书的技术文档也很赞，
AWS 的技术文档灰常详细，但是普通人就是看不懂。。。 |
 |
36
JerryCha 2021-06-04 23:15:23 +08:00
方案一天 3 变，早上做的东西指不定晚上就废弃。需求天天在变，快节奏赶需求的情况下很难产生高质量的文档。
|
 |
37
Huelse 2021-06-04 23:20:35 +08:00 1
目前个人认为 rust 的文档最舒适，有兴趣的可以看看 https://doc.rust-lang.org/book/
|
 |
38
l12ab 2021-06-04 23:48:16 +08:00 via iPhone
国内的，以前觉得 leancloud 的文档不错
|
 |
39
roundgis 2021-06-04 23:54:26 +08:00 via Android
我曾經做過一段時間的所謂文檔工程師
就是單純幫開發組寫文檔 薪資也不高，當時大約 20k 港幣 公司要捨得花錢 |
 |
40
serverABCD 2021-06-05 00:25:57 +08:00
@huifer 你别编程了，不适合这个行业
|
 |
41
acmore 2021-06-05 00:31:14 +08:00 1
支持楼主的观点。
这跟你是不是冰箱没有关系，不管你是个啥，面前这个冰箱不制冷那就是不好的，就是应该被吐槽的。 你自己不制冷是另一回事，楼上某些人不必偷换概念。 |
 |
42
iyaozhen 2021-06-05 00:47:40 +08:00 1
之前项目有一版的接口文档是我参与写的（我是 QA ）。
直接说结论：没有收益 要想写好文档非常的难，需要考虑很多场景（不止是列出参数，还得教被人怎么用，写各个语言的示例代码），翻很多代码（即使多人协作，总得有人 review 全部的），还需要保持更新。而且一般的同学还写不了，还得高工写，这样的话又耗时间又没收益。 |
 |
43
mxT52CRuqR6o5 2021-06-05 01:41:41 +08:00 via Android
写好文档有 roi 吗，反正我都垄断了，你不用也得用
|
 |
44
namelosw 2021-06-05 02:36:40 +08:00 1
Stripe / Twilio 的 API 最好，文档也很不错。
文档好不好主要取决于公司和团队的 mindset： 1. 不好的公司和团队：文档就是累赘，开发完了，写文档就是顺便应付鬼子。个人想写好只能硬挤时间完善，对 performance 完全没有帮助。 2. 好的公司和团队：一个功能没有文档 = 这个功能不存在。一个功能没有好的文档，等于任务只完成了一半。优化文档是每个人职责的重要组成部分，因此也会影响 performance 。 还有一些团队文档驱动开发，先把文档迭代到自己真的会爱用的程度再去实现。 |
 |
45
levelworm 2021-06-05 02:50:40 +08:00
写需求，写文档，都是吃力不讨好但是长远看比较重要的两件事情。所以这事情还是得公司或者组给力。
不过互联网风、业务驱动的公司我觉得可能都没时间，一切从快。。。外加业务话语权最大可以随便换需求，换来换去需求文档都变成屎了。 |
 |
47
xarthur 2021-06-05 06:25:22 +08:00 via iPhone
我一直觉得接口文档之类的其实需要直接从代码和注释里生成。
|
 |
48
dayeye2006199 2021-06-05 07:46:15 +08:00
拿手写文档的基本不成。得根据注释、类型之类的信息直接从代码里面生成出来，才能保证不断更新。
|
 |
49
ragnaroks 2021-06-05 08:01:53 +08:00
文档天花板 --MSDN
|
 |
50
yikyo 2021-06-05 09:23:19 +08:00
印象中微信有个文档 字段的大小写错了，导致报错，还找不到原因。
|
 |
51
sleepm 2021-06-05 09:34:35 +08:00
又不是不能用
不过话说回来，文档一直是变化最慢的 |
 |
52
lovecy 2021-06-05 10:15:46 +08:00
你想要的写得好的文档，是你自己看得舒服的哪种，说不定另一个人来看又不舒服了。
这东西貌似也没有大家都认可的规范啥的，我一直觉得只要不遗漏重要的点就算好文档了。。 |
 |
54
zxcslove 2021-06-05 10:36:17 +08:00
冷嘲热讽的渣渣真是可耻
|
 |
56
byron 2021-06-05 15:29:58 +08:00 1
支付宝文档有捉虫奖励。
包括楼主说的错别字、功能缺失、内容缺失、demo 示例错误、流程无法跑通、上下文描述不一致、内容错误、错误的超链接、产品类错误 等。 捉虫范围 开放平台文档中心： https://openhome.alipay.com/docCenter/docCenter.htm 主要模块包括： • 小程序 • 网页&移动应用 • 生活号 • 第三方应用 • IoT • 插件 活动地址： https://forum.alipay.com/mini-app/post/41201012?from=opendocs-activity |
 |
57
hotsymbol 2021-06-05 21:25:41 +08:00
AWS，Azure，Google Cloud 的文档就很友好
|
Select Language