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