作者:小智 苹果的 App Store 审核之严格,大家都有所耳闻。但在苹果公司的平台上写代码,似乎却不是那么一件令人身心愉快的事儿。本文主人公 Chris Krycho 是一位前端开发,他直言不讳地表示:苹果的开发者文档就是垃圾。为什么这样说呢? 开发者:苹果,你的文档糟透了! Chris Krycho 过去五年中一直在从事 JavaScript 前端开发的工作。过去几个月时间里,他一直在努力跟上苹果开发者生态系统的发展速度,并且将这一切作为自己的 rewrite 项目中的一部分。(注:rewrite 是 Chris 的个人项目,目的是构建一个跨平台的面向学术研究的写作环境) Chris 此前一直在学习 Swift、SwiftUI 以及 iOS 和 macOS API 等相关知识。于是他震惊了:
作为一个使用过 AngularJS、Ember.js 的前端开发,Chris 表示:Ember 的文档质量怎么样大家都懂的。但在他的四年实际使用中,他亲眼见证了 Ember 的文档从“勉强能用”一路发展到“相当完善”。还有 AngularJS,五年前刚刚接触它的 Chris 常常陷入崩溃:文档严重缺少对核心概念的解释,要么就是解释不知所云。他只能在绝望中求助他人,但他人通常也处于一种薛定谔的理解状态,介于懂或不懂之间。
没想到,Chris 还是太年轻。
Chris 在苹果平台开发的感受,跟笔者的工作签名颇为相似:Everyday Struggle。 在 Chris 看来,苹果的开发平台、工具里,也就 Swift 还好一点,文档写得质量不错,维护也相对到位。
大部分 SwiftUI 完全没有文档记录,甚至没有一行代码解释给定的类型或修饰符的作用。Swift Package Manager 的文档还不错,但是也很难从官方文档中了解到它能做什么,不能做什么。Chris 的很多问题都只能面向 Stack Overflow 解决,他甚至不得不反复阅读那些 WWDC 大会上的文字材料,看看有没有人提过跟他当前工作内容有关的信息。 他表示这种情况完全不合理:
但无论如何,只要公开 API,那么只有发布对应的说明文档,开发才算真正完成。 在 Chris 看来,这个锅不能扣给某个单独的软件工程师,责任甚至也不再专门的文档团队成员。他认为,这纯粹就是苹果公司在工程组织方面的失败。API 工程部门的人物,就是为使用 API 的受众提供支持,苹果的工程师肯定是希望同步提供对应的说明文档的,但为什么没有呢?Chris 猜测一是该团队人力严重不足,要么就是苹果公司的工程文化里根本就不重视文档。
网友怎么看 Chris 的控诉得到了广大苹果生态下开发者们的声援,他们纷纷表示:你不是一个人! 有的强调了文档的重要性:
有的在分析为什么没人写文档:
有分享自己用三分钟放弃苹果 API 故事的:
有的在批评苹果公司的傲慢与自大:
有的给苹果支招,看看友商是怎么做的:
如何才能写出好的设计文档? 程序员对文档的态度有着一种矛盾的情感,一方面,需要依赖于文档获取相关开发知识,另一方面,又很少有人愿意写文档。而不愿意写文档的人群中,又有不少是因为不能结构化地输出自己的开发知识。 读文档和写文档,一个输入,一个输出,一个读者,一个作者。想要成为一个好程序员,有一个良好的知识结构是极其重要的。试着去用结构化的思维写文档吧,功在当代,利在千秋。 一篇好的文档应该包含需求、设计目标、系统架构、模块简介、潜在风险等方面,在写作上又应该遵循以下要点:
|