写点什么

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

  • 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:008121
用户头像
小智 让所有人认同的文字称不上表达

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

关注

评论 2 条评论

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

浅谈分布式事务

Java 程序员 后端

浅谈物联网开发最热协议—MQTT协议

Java 程序员 后端

消息中间件

Java 程序员 后端

深入浅出MySQL - MyISAM有趣的那些“锁”事儿

Java 程序员 后端

深入理解Java类加载器(一):Java类加载原理解析

Java 程序员 后端

深入理解JAVA虚拟机原理之Dalvik虚拟机(三)

Java 程序员 后端

求职经历,三轮技术面 +HR 面,面试也不过如此

Java 程序员 后端

没用过这些 VSCode 插件?怪不得写代码头疼

Java 程序员 后端

消息发送常见错误与解决方案

Java 程序员 后端

浅谈Java开发规范与开发细节(下)

Java 程序员 后端

深入理解Java String类

Java 程序员 后端

渣本Java开发小伙如何一步步成为架构师?回首看来,每一步都不容易(1)

Java 程序员 后端

漫谈一条SQL语句的一生

Java 程序员 后端

深入理解JAVA虚拟机原理之内存分配策略(二)

Java 程序员 后端

清幽现云山,虚静出内功。阿里《Java开发手册》最新嵩山版发布

Java 程序员 后端

渣本Java开发小伙如何一步步成为架构师?回首看来,每一步都不容易

Java 程序员 后端

源码分析ElasticJob选主实现原理

Java 程序员 后端

没想到-Springboot-+-Flowable-开发工作流会如此简单

Java 程序员 后端

泪目!跳槽太不容易了,美团4轮面试,四个小时灵魂拷问,结局我哭了!

Java 程序员 后端

浅谈(chain of responsibility)责任链模式

Java 程序员 后端

深入理解MySQL索引

Java 程序员 后端

源码分析Dubbo 泛化调用与泛化实现原理

Java 程序员 后端

注解式限流是如何实现的?

Java 程序员 后端

测试用例的设计方法及案例

Java 程序员 后端

淦!阿里限产新一代微服务+K8S+容器进阶笔记,实战理论满满

Java 程序员 后端

深入理解什么是端口(port)

Java 程序员 后端

毕业参加工作了,记住一句话,攒钱绝对靠谱

Java 程序员 后端

泪洒阿里,面试惜败闭关2月金九银十再战Alibaba!

Java 程序员 后端

深入学习Kafka数据消费大致流程(如何创建并使用Kafka消费者)

Java 程序员 后端

源码分析Dubbo服务消费端启动流程

Java 程序员 后端

爱了,在GitHub超火的Java程序性能优化实战笔记,实在太香!

Java 程序员 后端

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