【AICon】探索RAG 技术在实际应用中遇到的挑战及应对策略!AICon精华内容已上线73%>>> 了解详情
写点什么

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

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

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

关注

评论 2 条评论

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

架构误区系列18:error、warn不分

agnostic

日志级别

第12期 | 用友BIP项目云,助力施工项目全过程、全要素创新发展

用友BIP

项目管理

数字化时代的软件供应链管理新标杆 - 华为云制品仓CodeArts Artifact

YG科技

Python笔记二之多线程

Hunter熊

Python 多线程

Go1.21.0 程序启动过程

-Hedon🍭

Go 语言 Go程序启动流程 Go1.21 Go 底层原理

程序员35+危机如何破?

智慧源点

副业赚钱

建立个人学习观|地铁上的自习室

阿里技术

个人学习观 学习观 思想观念

app开发

Geek_8da502

昇腾AI开发者创享日·广州站成功举办 四大仪式激发人工智能产业创新活力

彭飞

京东商品详情接口在电商行业中的重要性及实时数据获取实现

Noah

华为云数字化制品仓,引领企业智能化转型之路

YG科技

制品仓智能化管理,引领数字化时代的软件供应链变革

YG科技

毫无意义或有深意?工作反思手册

少油少糖八分饱

职场 工作 价值 生活的意义 工作价值

一款基于ESP32的迷你四足机器人

攻城狮Wayne

华为云制品仓库:引领数字化未来的巨量引擎

YG科技

当代数据库领域先驱者 Mohan 教授、ASF 成员 Julian 博士莅临天谋科技参观指导

Apache IoTDB

驱动优化做盾,性能提升为矛,看英特尔锐炫GPU如何破壁生态与创新

E科讯

2024 年最值得推荐的 7 个 Vue3 组件库

Kagol

低代码开发到底是补品还是垃圾食品?

伤感汤姆布利柏

Wireshark使用技巧

小魏写代码

1688商品详情接口在电商行业中的重要性及实时数据获取实现

Noah

解锁未来软件安全的利器——华为云CodeArts开源治理服务

YG科技

极狐GitLab 与 Flux 集成实现 GitOps

极狐GitLab

开源 DevOps gitlab gitops Flux

用友与上海国家会计学院联合主办第六届智能财务高峰论坛

用友BIP

智能会计

《公立医院成本核算指导手册》印发 公立医院应该如何做好成本核算

用友BIP

成本管理

说到CR,我们到底需要关注什么

agnostic

CR

HashData:大数据时代的“追光者”

酷克数据HashData

智能软件仓储如何选择?华为云制品仓助力企业勇攀高峰

YG科技

华为云制品仓CodeArts Artifact:引领数字化风潮,解锁企业未来

YG科技

文心一言 VS 讯飞星火 VS chatgpt (153)-- 算法导论12.2 9题

福大大架构师每日一题

福大大架构师每日一题

做好技术分享需要注意的几点(第三点很重要)

Java 工程师蔡姬

#java 21 天技术人写作行动营 #技术分享

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