V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
richChou
V2EX  ›  程序员

又是看 API 文档崩溃的一天

  •  1
     
  •   richChou ·
    zhoujunjie221 · 2021-06-04 15:22:15 +08:00 · 6695 次点击
    这是一个创建于 1029 天前的主题,其中的信息可能已经有所发展或是发生改变。
    从业多年几乎没看到过一份合格的 API 文档。

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

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

    拜托各位业务负责人、各个 Leader 、还有写文档的铁子们,写文档的时候稍微多花点心思,节约大家的沟通成本。皆大欢喜不好吗?
    57 条回复    2021-06-05 21:25:41 +08:00
    memedahui
        1
    memedahui  
       2021-06-04 15:28:41 +08:00
    支付宝我觉得是最好的,没有之一
    AoEiuV020
        2
    AoEiuV020  
       2021-06-04 15:29:30 +08:00   ❤️ 22
    程序员最讨厌的四件事:写注释,写文档,别人不写注释,别人不写文档
    huifer
        3
    huifer  
       2021-06-04 15:30:28 +08:00   ❤️ 6
    你可以写一个优质的文档让我们看看吗
    Tianao
        4
    Tianao  
       2021-06-04 15:33:24 +08:00 via iPhone
    @huifer #3 同样是面向业务流程的,GitHub 的、Cloudflare 的就都很优质,不谢。
    freakxx
        5
    freakxx  
       2021-06-04 15:41:22 +08:00
    天降正义:
    所有事情都漂漂亮亮地处理好,就等着我按下关键的按钮。
    richChou
        6
    richChou  
    OP
       2021-06-04 15:57:45 +08:00   ❤️ 11
    @freakxx
    @huifer
    1. 文档的目的是产品服务给别人使用的时候,可以便捷地完成接入
    2. 我们经常作为服务提供方、也是服务使用方,应该可以明白节省沟通成本是双赢的事情吧?
    3. 一个合理且没有恶意的吐槽,如果你有不同的看法可以聊聊,这样冷嘲热讽挺没意思的
    qwertyzzz
        7
    qwertyzzz  
       2021-06-04 16:00:52 +08:00
    你可以写一个优质的文档让我们看看吗
    sprite82
        8
    sprite82  
       2021-06-04 16:09:43 +08:00   ❤️ 8
    看楼上冷嘲热讽的,类似冰箱有问题我还得会制冷
    balabalaguguji
        9
    balabalaguguji  
       2021-06-04 16:10:35 +08:00   ❤️ 1
    请看优质的文档: https://easydoc.net/doc/30486560/ae8DEKDo/0wgri5M2

    用易文档写接口文档很方便
    cmdOptionKana
        10
    cmdOptionKana  
       2021-06-04 16:20:26 +08:00
    这个程序员的责任是次要,公司管理层负主要责任,要么对程序员写文档给予某种形式的奖励或鼓励,要么另外请专人写文档。不然写文档吃力不讨好,当然不爱写。
    zhengsidao
        11
    zhengsidao  
       2021-06-04 16:25:13 +08:00
    有一说一,写接口文档国内真的是不太行
    REST 参数名称 过去式 单复数都没有很好的遵守,可以看看谷歌的一些 API 接口信息,老外的 SaaS 服务为了保证对接一般都写的还可以....
    AoEiuV020
        12
    AoEiuV020  
       2021-06-04 16:25:54 +08:00   ❤️ 5
    @sprite82 别类似,你也是个冰箱,确实要会制冷,
    freakxx
        13
    freakxx  
       2021-06-04 16:44:26 +08:00   ❤️ 1
    @richChou #6

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

    还是挺有意思的。

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



    这个事情,我只是觉得,你说这几家的文档烂嘛,已经做得挺不错的,说难用嘛,很多时候,历史遗留的问题,是留了很多坑坑挖挖;
    只是很多时候,文档好不好用,在某些时候,变得不好用,这个是有部分主观的问题的;
    这个事情是需要宽容一点的。
    freakxx
        14
    freakxx  
       2021-06-04 16:48:28 +08:00
    @sprite82 #8

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


    就这个角度来说,你也是个冰箱,你能展示下 100%优质的制冷效果来看看?
    z54749412
        15
    z54749412  
       2021-06-04 16:52:39 +08:00
    @memedahui 支付宝小程序不是抄的微信的?这么说就是微信比较牛批了么?
    z54749412
        16
    z54749412  
       2021-06-04 16:54:10 +08:00
    @memedahui 少打了文档两个字,,非常抱歉
    freakxx
        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
    InkAndBanner
        18
    InkAndBanner  
       2021-06-04 17:51:48 +08:00   ❤️ 1
    微信小商店的 api 也一样 文档仿佛是为了骗我而存在的
    AngryPanda
        19
    AngryPanda  
       2021-06-04 18:05:18 +08:00
    @balabalaguguji 感觉美观上差了点意思
    raaaaaar
        20
    raaaaaar  
       2021-06-04 18:07:35 +08:00 via Android
    我一直是很重视可读性,规范这种东西的,不过突然有一天有人跟我说注释写得太少。。
    tachikomachann
        21
    tachikomachann  
       2021-06-04 18:07:51 +08:00 via Android   ❤️ 4
    ls 吐槽 lz 的原因应该是:你在抱怨国内文档写不好,但是没举个具体的例子,或者给出个写得好的范例。
    不知道 lz 有没有做过技术客服。之前的工作做过这方面的工作一段时间,发现好的文档真的很难写,因为用户的水平参差不齐,知识背景不一样,对于同一段内容有些人就是觉得看不懂。当然还有部分原因是写文档的人本身对自己的产品是足够了解的,很难站在一个纯用户的角度组织语言。
    所以我觉得很多时候光靠文档是不够的,训练有素的客服,氛围不错的社区都有助于提高沟通效率。
    WhiteDragon96
        22
    WhiteDragon96  
       2021-06-04 18:13:20 +08:00
    1.没时间写,写文档的时间并不会算你工作时间
    2.写好了也没人会表扬,写的差也没人说
    3.能用就行
    mogg
        23
    mogg  
       2021-06-04 18:28:16 +08:00
    微信支付这文档已经做的不错了吧,把场景相关的都讲了一遍……
    https://pay.weixin.qq.com/wiki/doc/api/micropay.php?chapter=1_1
    laduary
        24
    laduary  
       2021-06-04 18:42:49 +08:00
    @huifer 请参阅在线支付平台 Stripe 的文档: https://stripe.com/docs
    fiypig
        25
    fiypig  
       2021-06-04 18:46:05 +08:00 via iPhone
    哈哈哈哈,一些第四方支付更扯,有些是真的简单,一些是数据类型不匹配,有些是神操作加密。
    cking
        26
    cking  
       2021-06-04 18:47:48 +08:00
    @AoEiuV020 死循环 无解
    touchwithe
        27
    touchwithe  
       2021-06-04 21:16:11 +08:00 via iPhone
    AWS 的文档是真漂亮!此处特别点名批评阿里云。
    yin1999
        28
    yin1999  
       2021-06-04 21:50:04 +08:00
    @touchwithe 移动云表示不服
    rabbitofyou
        29
    rabbitofyou  
       2021-06-04 21:51:47 +08:00
    你会发现无从改起 么有统一标准。。
    anguiao
        30
    anguiao  
       2021-06-04 21:55:44 +08:00 via Android   ❤️ 1
    这种对外提供服务的 API 文档,和企业内部文档根本不能相提并论。这方面不知道楼上这些冷嘲热讽的是什么意思。
    写文档确实是个技术活,这种用户很多的文档,应该有专门的人来负责,而不是靠程序员在写代码的时候随便写写。
    stevenhawking
        31
    stevenhawking  
       2021-06-04 22:12:37 +08:00
    支付宝、微信支付、微信公众号、微信小程序的文档都是太屎之作。
    大厂写出这种狗屎应该感到耻辱。
    israinbow
        32
    israinbow  
       2021-06-04 22:17:46 +08:00
    我有写文档写注释写说明书的习惯,
    但是也有代码写着写着忘了写上述内容的习惯,
    最后就, 写了半俩的文档和断断续续的注释和有头无尾或者只有大纲和待办事项的说明书.
    ╮(╯▽╰)╭
    janxin
        33
    janxin  
       2021-06-04 22:49:39 +08:00
    目前国内还没接过比较好的 API 文档的例子,国外几个接的服务文档有几个还比较不错,但是也有一看就是开发自己糊了糊的。。。
    Lemeng
        34
    Lemeng  
       2021-06-04 23:07:34 +08:00
    文档都不喜欢写。呼吁也作用不大。除非有标准
    akira
        35
    akira  
       2021-06-04 23:10:30 +08:00
    文档做的最好的应该是微软了吧,谷歌脸书的技术文档也很赞,
    AWS 的技术文档灰常详细,但是普通人就是看不懂。。。
    JerryCha
        36
    JerryCha  
       2021-06-04 23:15:23 +08:00
    方案一天 3 变,早上做的东西指不定晚上就废弃。需求天天在变,快节奏赶需求的情况下很难产生高质量的文档。
    Huelse
        37
    Huelse  
       2021-06-04 23:20:35 +08:00   ❤️ 1
    目前个人认为 rust 的文档最舒适,有兴趣的可以看看 https://doc.rust-lang.org/book/
    l12ab
        38
    l12ab  
       2021-06-04 23:48:16 +08:00 via iPhone
    国内的,以前觉得 leancloud 的文档不错
    roundgis
        39
    roundgis  
       2021-06-04 23:54:26 +08:00 via Android
    我曾經做過一段時間的所謂文檔工程師

    就是單純幫開發組寫文檔

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

    公司要捨得花錢
    serverABCD
        40
    serverABCD  
       2021-06-05 00:25:57 +08:00
    @huifer 你别编程了,不适合这个行业
    acmore
        41
    acmore  
       2021-06-05 00:31:14 +08:00   ❤️ 1
    支持楼主的观点。
    这跟你是不是冰箱没有关系,不管你是个啥,面前这个冰箱不制冷那就是不好的,就是应该被吐槽的。
    你自己不制冷是另一回事,楼上某些人不必偷换概念。
    iyaozhen
        42
    iyaozhen  
       2021-06-05 00:47:40 +08:00   ❤️ 1
    之前项目有一版的接口文档是我参与写的(我是 QA )。

    直接说结论:没有收益

    要想写好文档非常的难,需要考虑很多场景(不止是列出参数,还得教被人怎么用,写各个语言的示例代码),翻很多代码(即使多人协作,总得有人 review 全部的),还需要保持更新。而且一般的同学还写不了,还得高工写,这样的话又耗时间又没收益。
    mxT52CRuqR6o5
        43
    mxT52CRuqR6o5  
       2021-06-05 01:41:41 +08:00 via Android
    写好文档有 roi 吗,反正我都垄断了,你不用也得用
    namelosw
        44
    namelosw  
       2021-06-05 02:36:40 +08:00   ❤️ 1
    Stripe / Twilio 的 API 最好,文档也很不错。

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

    还有一些团队文档驱动开发,先把文档迭代到自己真的会爱用的程度再去实现。
    levelworm
        45
    levelworm  
       2021-06-05 02:50:40 +08:00
    写需求,写文档,都是吃力不讨好但是长远看比较重要的两件事情。所以这事情还是得公司或者组给力。
    不过互联网风、业务驱动的公司我觉得可能都没时间,一切从快。。。外加业务话语权最大可以随便换需求,换来换去需求文档都变成屎了。
    levelworm
        46
    levelworm  
       2021-06-05 02:51:41 +08:00
    @namelosw 文档驱动开发我觉得蛮好的,搞得好的话,弄不好可以半自动化。当然前提是需求搞清楚,框架搭起来。
    xarthur
        47
    xarthur  
       2021-06-05 06:25:22 +08:00 via iPhone
    我一直觉得接口文档之类的其实需要直接从代码和注释里生成。
    dayeye2006199
        48
    dayeye2006199  
       2021-06-05 07:46:15 +08:00
    拿手写文档的基本不成。得根据注释、类型之类的信息直接从代码里面生成出来,才能保证不断更新。
    ragnaroks
        49
    ragnaroks  
       2021-06-05 08:01:53 +08:00
    文档天花板 --MSDN
    yikyo
        50
    yikyo  
       2021-06-05 09:23:19 +08:00
    印象中微信有个文档 字段的大小写错了,导致报错,还找不到原因。
    sleepm
        51
    sleepm  
       2021-06-05 09:34:35 +08:00
    又不是不能用
    不过话说回来,文档一直是变化最慢的
    lovecy
        52
    lovecy  
       2021-06-05 10:15:46 +08:00
    你想要的写得好的文档,是你自己看得舒服的哪种,说不定另一个人来看又不舒服了。
    这东西貌似也没有大家都认可的规范啥的,我一直觉得只要不遗漏重要的点就算好文档了。。
    lovecy
        53
    lovecy  
       2021-06-05 10:17:46 +08:00
    @iyaozhen 而且就算有一份非常详细的文档,也没法避免伸手党问这问那的
    zxcslove
        54
    zxcslove  
       2021-06-05 10:36:17 +08:00
    冷嘲热讽的渣渣真是可耻
    Stain5
        55
    Stain5  
       2021-06-05 15:26:15 +08:00
    @AoEiuV020 准确来说是看公司价值观吧

    写文档轻松 不用掉头发

    如果工期宽长 有有人认可的话
    byron
        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
    hotsymbol
        57
    hotsymbol  
       2021-06-05 21:25:41 +08:00
    AWS,Azure,Google Cloud 的文档就很友好
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   3597 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 36ms · UTC 10:30 · PVG 18:30 · LAX 03:30 · JFK 06:30
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.