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

文章来自微信公众号：InfoQ（ID：infoqchina），作者：小智，题图来自：东方IC

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

开发者：苹果，你的文档糟透了！

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

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

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

作为一个使用过 AngularJS、Ember.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猜测一是该团队人力严重不足，要么就是苹果公司的工程文化里根本就不重视文档。

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

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

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

网友怎么看

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

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

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

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

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

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

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

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

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

有的给苹果支招，看看友商是怎么做的：

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

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

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

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

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

尽可能保持简单；

添加图表以可视化；

包含数字更为具体；

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

做好自审，以评审者的角度去看文档；

假期测试，看其他人能否读懂、实现；

流程环节完备，关键人物参与其中；

文章来自微信公众号：InfoQ（ID：infoqchina），作者：小智