GMTC 全球大前端技术大会 8 折涨价倒计时 2 天,现在购票立减 ¥960 ! 了解详情
写点什么

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

2019 年 10 月 30 日

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

苹果的 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:005151
用户头像
小智 前 InfoQ 主编

发布了 400 篇内容, 共 318.0 次阅读, 收获喜欢 1761 次。

关注

评论 2 条评论

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

内容审核平台助力猫爪构建健康安全的社交环境

百度大脑

人工智能 百度 百度大脑 内容审核

JVM原理与实战

东哥

jQuery笔记

一个坚强的小怪兽

jquery

第11周作业

娄江国

英特尔神经拟态芯片Loihi大显身手 帮助轮椅上的儿童实现独立生活

最新动态

CHAR与VARCHAR详解

Simon

MySQL

linux入门系列10--firewalld防火墙管理

黑马腾云

Linux centos 防火墙 linux运维 linux防火墙

非IT行业大企程序员讲述MIS系统开发案例

Learun

敏捷开发 企业信息化 企业管理 .net core 「Java 25周年」

企业信息化怎么构建?

代码制造者

大数据 低代码 企业信息化 零代码 编程开发

开源,轻松实现RTC与SIP互通

anyRTC开发者

WebRTC 编码 SIP 源码解析

35岁大厂程序员被劝退!老板说:没年轻人有冲劲!真有内味了吗?

程序员生活志

程序员 职场

​JDK1.8新特性(八):还在重复写空指针检查代码?赶紧使用Optional吧!​

xcbeyond

Java 新特性 JDK1.8 Optional JDK1.8新特性

学习笔记

Qx

学习

SkyWalking为超大规模而生

热心的朝阳群众

Skywalking 开源社区

linux入门系列7--管道符、重定向、环境变量

黑马腾云

Linux centos 运维 linux命令 管道符

没有一个冬天不会过去!疫情当下,企业“逆势而上”必选“上云”跑道

华为云开发者社区

云计算 新基建 华为云 企业上云 云服务器

区块链技术助力甘肃建食安信息追溯平台 为食品安全“立规矩”

CECBC区块链专委会

食品追溯 食品安全

Devops与敏捷二者能否结合?

禅道项目管理

DevOps Scrum 敏捷开发

linux入门系列9--用户管理及文件权限控制

黑马腾云

Linux centos centos7 linux运维 linux用户权限

区块链的想象,解决贫富差距

CECBC区块链专委会

区块链 货币 股市

可能是首个支持部署 Deno 前后端应用的部署工具

binggg

taro GitHub 前端 deno Node

全票通过!易观开源项目DolphinScheduler进入Apache孵化器

易观大数据

英伟达收购ARM:双赢还是灾难?

脑极体

INT类型知多少

Simon

MySQL

网页游戏

小端taro

第11周总结

娄江国

物联网SIM卡和SIM卡真的不是一回事

华为云开发者社区

人工智能 物联网 华为云 传感器 SIM卡

linux入门系列8--shell编程入门

黑马腾云

Linux centos Shell linux命令 linux编程

要老婆吗? AR一键生成的那种

程序员生活志

学习python(嵩天老师的课)

Geek_2a27b0

终极学习法,你能学会任何东西--程序员的学习之路

盛安德软件

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