AI实践哪家强?来 AICon, 解锁技术前沿,探寻产业新机! 了解详情
写点什么

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

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

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

关注

评论 2 条评论

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

实践解读丨Python 面向对象三大特征之多态

华为云开发者联盟

编程 面向对象

分布式数据库拆分常用之法

华为云开发者联盟

数据库 架构 分布式

智能商业时代的思考(三)数据驱动

刘旭东

大数据 数据驱动 智能商业

使用递增计数器的线程同步工具 —— 信号量,它的原理是什么样子的?

程序员小航

Java 源码 源码阅读 JUC Semaphore

rpc探路(一)

余歌

测试工程师在敏捷项目中扮演什么角色?

禅道项目管理

程序员 敏捷开发 测试

谈谈力软快速开发平台B/S专业报表工具

Philips

敏捷开发 开发工具

Golang框架探索(一)

余歌

Web框架 Go web

架构设计:微服务架构如何划分?这6个标准原则让你一目了然

互联网应用架构

微服务 架构设计

收藏手册:该不该用Lombok?15个常用注解全解析

互联网应用架构

lombok

(0)skynet序章

休比

科大讯飞再握一国产核心技术,可高精细拾取30分贝超小音量

Talk A.I.

springboot2.3手册:多租户及自动创建数据,这样做

互联网应用架构

springboot mybaitsplus 多租户 自动填充基础信息

Kotlin 插件1.4.10使用报错

三爻

android kotlin

站在巨人的肩膀上学习:五位阿里大牛联手撰写的《深入浅出Java多线程》

Java架构之路

Java 编程 面试 并发编程 多线程

java安全编码指南之:输入校验

程序那些事

java安全编码 安全编码规范 java安全编码指南

从linux源码看socket的阻塞和非阻塞

无毁的湖光

Linux TCP socket Linux Kenel

Java ConcurrentHashMap 高并发安全实现原理解析

vivo互联网技术

Java hashmap 多线程 高并发

大作业2

雪涛公子

拆分链表、图解HTTPS、Zookeeper原理、如何成为技术专家、架构师三板斧 John 易筋 ARTS 打卡 Week 18

John(易筋)

ARTS 打卡计划 图解https ZooKeeper原理 架构师三板斧 拆分链表

我的 2020 iOS BAT面试心得:Bigo、字节、快手、伴鱼、百度、微博等

iOSer

ios 面试

Golang 反射性能优化

余歌

性能优化 Go 语言

第十一周.命题作业

刘璐

RDS、DDS和GaussDB理不清?看这一篇足够了!

华为云开发者联盟

数据库 华为云 RDS

JavaScript原型机制

Clloz

Java 原型

收藏手册:Docker安装RabbitMQ,只需3步

互联网应用架构

Docker RabbitMQ

Java开发连Redis都不会还想跳槽涨薪?先把Redis的知识点吃透再说

Java架构之路

Java redis 编程 程序员 面试

LeetCode题解:144. 二叉树的前序遍历,递归,JavaScript,详细注释

Lee Chen

大前端 LeetCode

高难度对话读书笔记

wo是一棵草

Java新特性:数据类型可以扔掉了?

Java 编程 架构师

当代开发者的好帮手,浅析.NET敏捷开发框架的优势与特点

Learun

敏捷开发 开发工具

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