开发者技术前线 ,汇集技术前线快讯和关注行业趋势,大厂干货,是开发者经历和成长的优秀指南。
腾讯全文检索引擎 wwsearch 正式开源
这一顿神操作!我把 3000 行代码重构成 15 行!
又一个新操作系统发布!号称史上最漂亮的系统,是 Windows /macOS 完美的替代品
2020 年九大顶级 Java 框架
The following article is from InfoQ Author 唐小智
点击“开发者技术前线”,选择“星标🔝”
在看|星标|留言, 真爱
坦白讲,苹果生态系统的文档完备度之低,让我感到难以理解。
在我看来,对于开放 API 的大型科技企业来说,像 Ember、AngularJS 的文档这样,是一种糟糕甚至可怕的状态。
苹果才是文档质量低下方面的 No.1,我所接触的任何框架都不能与之匹敌……
但也就那样了。
在 Ember 生态系统中,我们有一条简单的规则,即除非配有说明文档,否则无法提交代码。Rust 也是如此(我曾经参与官方策略 rfc 的编写工作)。而在亲身接触之后,我意识到苹果的 API 开发人员(通常)不太清楚开源项目的运作方式——这可能是因为他们的交付流程不只涉及软件,而是更多围绕硬件产品进行。
苹果公司宣称有意打造一套所有人都能够使用的平台,包括刚刚接触编程的新人开发者,乃至拥有数十年开发经验的老专家。但直到现在,苹果也没能真正实现这一目标。
我已经拥有十年的软件开发经验,而且大部分成果都是通过具有丰富类型的系统与函数编程式语言开发完成的。我得承认,作为一名没啥天赋的开发者,其中不少东西弄得我头大如斗、难以理解。我甚至不敢想象对于刚刚开始使用开发框架,或者仅仅接触过 Ruby、Python 或者 JavaScript 等主流语言的新人来说,直接面对苹果的这套生态系统到底是种怎样的体验。毕竟没有了官方文档,学习将成为一项不可能完成的任务。
所以苹果公司,如果你真的希望开发人员爱上你家的平台,那最好早点重视文档完善工作,毕竟开发者是生态系统的命脉所在。如今这个时代,我们什么都缺,但最不缺的就是开发生态选项。面对其他巨头厂商的围追堵截,你苹果就真的毫不担心?我不信。最后,希望苹果能够从其他框架及语言项目身上取取经:没有文档,不算完成,其实就这么简单。
作为一个以文档记录工作为荣的人,我真的非常讨厌在软件开发中文档的价值被严重低估。文档常常会成就或打破一个产品。
我做过一段时间自由职业者,有一些公司找我帮忙写文档。相比起正式开发人员的高工资,这点钱比起来就是垃圾,所以我拒绝了。这说明什么?这些公司要么不重视文档,要么不给文档团队足够的薪资,大概率也不会给足够的时间。所以开发人员在构建环境时遇到这种问题,我一点都不奇怪。
上周我开始了一个新项目,必须在 Spotify API 和 MusicKit JS API 之间做出选择。Spotify 的文档,我要什么有什么,苹果的……大概是告诉了我什么是“艺术家资源”。
苹果似乎认为,只有他们才能掌握通往自己王国的所有钥匙。第三方开发人员是没有必要的,也不应该被信任。他们不允许开发者使用只有苹果才能使用的平台功能。它们没有提供良好的文档或开发工具。
看看微软的 Xamarin,人家用苹果的 API 都比苹果自己用得好。苹果你就是自己不上心。苹果要实在不想在文档上投入精力,也可以学学微软,让第三方通过 GitHub 贡献。(当然这种方式还是有一定问题,谨慎对待)
尽可能保持简单;
添加图表以可视化;
包含数字更为具体;
一定的趣味性让文档更耐读;
做好自审,以评审者的角度去看文档;
假期测试,看其他人能否读懂、实现;
流程环节完备,关键人物参与其中;
开发者技术前线 ,汇集技术前线快讯和关注行业趋势,大厂干货,是开发者经历和成长的优秀指南。