10 月 23 - 25 日,QCon 上海站即将召开,现在购票,享9折优惠 了解详情
写点什么

苹果,你的开发者文档写得烂透了

  • 2019-10-30
  • 本文字数:2515 字

    阅读完需:约 8 分钟

苹果,你的开发者文档写得烂透了

苹果的 App Store 审核之严格,大家都有所耳闻。但在苹果公司的平台上写代码,似乎却不是那么一件令人身心愉快的事儿。本文主人公 Chris Krycho 是一位前端开发,他直言不讳地表示:苹果的开发者文档就是垃圾。为什么这样说呢?

开发者:苹果,你的开发者文档糟透了!

Chris Krycho 过去五年中一直在从事JavaScript 前端开发的工作。过去几个月时间里,他一直在努力跟上苹果开发者生态系统的发展速度,并且将这一切作为自己的 rewrite 项目中的一部分。(注:rewrite 是 Chris 的个人项目,目的是构建一个跨平台的面向学术研究的写作环境)


Chris 此前一直在学习SwiftSwiftUI以及 iOS 和 macOS API 等相关知识。于是他震惊了:


坦白讲,苹果生态系统的文档完备度之低,让我感到难以理解。


作为一个使用过AngularJSEmber.js的前端开发,Chris 表示:Ember 的文档质量怎么样大家都懂的。但在他的四年实际使用中,他亲眼见证了 Ember 的文档从“勉强能用” 一路发展到“相当完善”。还有 AngularJS,五年前刚刚接触它的 Chris 常常陷入崩溃:文档严重缺少对核心概念的解释,要么就是解释不知所云。他只能在绝望中求助他人,但他人通常也处于一种薛定谔的理解状态,介于懂或不懂之间。


在我看来,对于开放API的大型科技企业来说,像 Ember、AngularJS 的文档这样,是一种糟糕甚至可怕的状态。


没想到,Chris 还是太年轻。


苹果才是文档质量低下方面的 No.1,我所接触的任何框架都不能与之匹敌……


Chris 在苹果平台开发的感受,跟笔者的工作签名颇为相似:Everyday Struggle。


在 Chris 看来,苹果的开发平台、工具里,也就 Swift 还好一点,文档写得质量不错,维护也相对到位。


但也就那样了。


大部分 SwiftUI 完全没有文档记录,甚至没有一行代码解释给定的类型或修饰符的作用。Swift Package Manager 的文档还不错,但是也很难从官方文档中了解到它能做什么,不能做什么。Chris 的很多问题都只能面向 Stack Overflow 解决,他甚至不得不反复阅读那些 WWDC 大会上的文字材料,看看有没有人提过跟他当前工作内容有关的信息。


他表示这种情况完全不合理:


在 Ember 生态系统中,我们有一条简单的规则,即除非配有说明文档,否则无法提交代码。Rust也是如此(我曾经参与官方策略 rfc 的编写工作)。而在亲身接触之后,我意识到苹果的 API 开发人员(通常)不太清楚开源项目的运作方式——这可能是因为他们的交付流程不只涉及软件,而是更多围绕硬件产品进行。


但无论如何,只要公开 API,那么只有发布对应的说明文档,开发才算真正完成。


在 Chris 看来,这个锅不能扣给某个单独的软件工程师,责任甚至也不再专门的文档团队成员。他认为,这纯粹就是苹果公司在工程组织方面的失败。API 工程部门的人物,就是为使用 API 的受众提供支持,苹果的工程师肯定是希望同步提供对应的说明文档的,但为什么没有呢?Chris 猜测一是该团队人力严重不足,要么就是苹果公司的工程文化里根本就不重视文档。


苹果公司宣称有意打造一套所有人都能够使用的平台,包括刚刚接触编程的新人开发者,乃至拥有数十年开发经验的老专家。但直到现在,苹果也没能真正实现这一目标。

我已经拥有十年的软件开发经验,而且大部分成果都是通过具有丰富类型的系统与函数编程式语言开发完成的。我得承认,作为一名没啥天赋的开发者,其中不少东西弄得我头大如斗、难以理解。我甚至不敢想象对于刚刚开始使用开发框架,或者仅仅接触过RubyPython或者JavaScript等主流语言的新人来说,直接面对苹果的这套生态系统到底是种怎样的体验。毕竟没有了官方文档,学习将成为一项不可能完成的任务。

所以苹果公司,如果你真的希望开发人员爱上你家的平台,那最好早点重视文档完善工作,毕竟开发者是生态系统的命脉所在。如今这个时代,我们什么都缺,但最不缺的就是开发生态选项。面对其他巨头厂商的围追堵截,你苹果就真的毫不担心?我不信。最后,希望苹果能够从其他框架及语言项目身上取取经:没有文档,不算完成,其实就这么简单。

网友怎么看

Chris 的控诉得到了广大苹果生态下开发者们的声援,他们纷纷表示:你不是一个人!


有的强调了文档的重要性:


作为一个以文档记录工作为荣的人,我真的非常讨厌在软件开发中文档的价值被严重低估。文档常常会成就或打破一个产品。


有的在分析为什么没人写文档:


我做过一段时间自由职业者,有一些公司找我帮忙写文档。相比起正式开发人员的高工资,这点钱比起来就是垃圾,所以我拒绝了。这说明什么?这些公司要么不重视文档,要么不给文档团队足够的薪资,大概率也不会给足够的时间。所以开发人员在构建环境时遇到这种问题,我一点都不奇怪。


有分享自己用三分钟放弃苹果 API 故事的:


上周我开始了一个新项目,必须在 Spotify API 和 MusicKit JS API 之间做出选择。Spotify 的文档,我要什么有什么,苹果的……大概是告诉了我什么是“艺术家资源”。


有的在批评苹果公司的傲慢与自大:


苹果似乎认为,只有他们才能掌握通往自己王国的所有钥匙。第三方开发人员是没有必要的,也不应该被信任。他们不允许开发者使用只有苹果才能使用的平台功能。它们没有提供良好的文档或开发工具。


有的给苹果支招,看看友商是怎么做的:


看看微软的Xamarin,人家用苹果的 API 都比苹果自己用得好。苹果你就是自己不上心。苹果要实在不想在文档上投入精力,也可以学学微软,让第三方通过 GitHub 贡献。(当然这种方式还是有一定问题,谨慎对待)

如何才能写出好的设计文档?

程序员对文档的态度有着一种矛盾的情感,一方面,需要依赖于文档获取相关开发知识,另一方面,又很少有人愿意写文档。而不愿意写文档的人群中,又有不少是因为不能结构化地输出自己的开发知识。


读文档和写文档,一个输入,一个输出,一个读者,一个作者。想要成为一个好程序员,有一个良好的知识结构是极其重要的。试着去用结构化的思维写文档吧,功在当代,利在千秋。


一篇好的文档应该包含需求、设计目标、系统架构、模块简介、潜在风险等方面,在写作上又应该遵循以下要点:


  • 尽可能保持简单;

  • 添加图表以可视化;

  • 包含数字更为具体;

  • 一定的趣味性让文档更耐读;

  • 做好自审,以评审者的角度去看文档;

  • 假期测试,看其他人能否读懂、实现;

  • 流程环节完备,关键人物参与其中;


你对文档怎么看?


2019-10-30 17:008127
用户头像
小智 让所有人认同的文字称不上表达

发布了 408 篇内容, 共 403.4 次阅读, 收获喜欢 1986 次。

关注

评论 2 条评论

发布
用户头像
如果开发者能克服社恐,这个问题就好解决了。文档不完善,那就直接发邮件问,用大量重复问题塞爆API提供者的邮箱,烦得他们不得不完善文档。
2019-10-31 09:11
回复
发邮件挺好的,精准
2019-10-31 09:14
回复
没有更多了
发现更多内容

AI 改变我们的工作方式 | 社区征文

宇宙之一粟

年中技术盘点

如何理解小程序插件?微信及支付宝官方详解

没有用户名丶

全面构建AI能力,AIFS为AI产业发展按下“加速键”

九章云极DataCanvas

《APaaS应用实施方法论》电子书正式发布

明道云

Filter for GO

数由科技

AI绘图:艺术与科技的交融 | 社区征文

IT蜗壳-Tango

年中技术盘点

《中国民用航空业零代码应用与推广白皮书》正式发布

明道云

阿里商旅账单系统架构设计实践

阿里技术

账单 阿里商旅 账单系统 账单数据

在 K8S 中只会 CI 不会 CD ?3 种方式,让极狐GitLab 和 K8S 高效协同!

极狐GitLab

DevOps 云原生 k8s CI/CD 集成

你的极狐GitLab SaaS上开启这些设置了吗?代码安全,安心下班!

极狐GitLab

gitlab CI/CD DevSecOps 代码安全 软件供应链安全

开源直播源码平台处理卡顿问题技巧方案_山东布谷科技创作

山东布谷科技

开源 软件开发 直播 源码搭建 直播源码

火山引擎DataTester:三类AB实验,让企业营销拥有灵敏“网感”

字节跳动数据平台

大数据 A/B测试 对比试验 企业号 7 月 PK 榜

前、后端通用的可视化逻辑编排

悠闲的水

低代码 逻辑编排 低代码平台 可视化编排 可视化开发

英特尔携钉钉及新华三以创新解决方案变革未来远程协作体验

E科讯

Nautilus Chain 主网上线,创世 ZBC 质押即将开启

鳄鱼视界

影响云安全的因素有哪些?如何保障云安全?

行云管家

云安全 企业上云 堡垒机 自动化运维 云管

模糊测试公布结果,大众漏洞被曝光

云起无垠

网络安全 模糊测试

Nautilus Chain 主网上线,创世 ZBC 质押即将开启

股市老人

第四届“先导杯”全国挑战赛正式开赛 百万奖金等你来拿

科技热闻

英特尔x MAXHUB:以创新解决方案掀起“智能协作”新浪潮

E科讯

Python爬虫超详细讲解(零基础入门,老年人都看的懂)

Java随想录

Java Python

【有奖互动】开发者版本新特性,你期待哪些更新?#HDC.Together2023#

HarmonyOS开发者

HarmonyOS

如何用极狐GitLab 为 Android App 创建自动化CI/CD?详细教程来了

极狐GitLab

自动化 CI/CD Android; keystore fastlane

一文讲透 Redis 事务 (事务模式 VS Lua 脚本)

不在线第一只蜗牛

Lua脚本 redis 底层原理 Redis 可视化工具

大模型时代下的全新变革

九章云极DataCanvas

苹果,你的开发者文档写得烂透了_文化 & 方法_小智_InfoQ精选文章