关于苹果的Piss-Poor文档
在过去的一两年里，我逐渐意识到，让我更难完成工作的第一件事就是文档。或者，更确切地说，是因为苹果为其平台提供的文档极度匮乏。
作为一名开发者，苹果为我们提供了一系列工具--API--让我们可以在iOS、iPadOS、MacOS和TVOS上开发应用程序。在许多情况下，弄清楚如何使用这些API是相当简单的。使用螺丝刀的方式有很多，同样，在很多情况下，使用API只有一种明显的方式。
然而，随着用户理所当然地要求更复杂、更花哨的应用程序，API软化也需要变得更花哨、更复杂。突然，你抬头一看，你不再只使用螺丝刀和锤子，而是使用电动工具和复杂的锯子，一切都比以前复杂得多。
有了真正的工具，你应该会收到一份用户手册，它解释了如何使用你刚刚购买的工具。对于API有一个粗略的类比，因为大多数平台供应商都会提供文档。这基本上是该API的所有者手册。
多年来，苹果的文档一直相当糟糕。在过去的几年里，它已经从Bad→Goad→卑鄙的→尴尬。我经常去研究如何做一些新的事情，并使用我不熟悉的API，结果却被这三个可怕的词所激励：
这是苹果公司说“去你妈的，你自己想办法”的方式。
没有任何可用的概述是如此糟糕，以至于一个受欢迎的苹果资源--本身可能不应该存在的东西--将其用作一个单一服务网站的同名网站，以突显苹果的文档有多糟糕。
进步的进军也无济于事。正如我的朋友亚当·斯温登(Adam Swinden)在Twitter上向我指出的那样，随着旧的API被弃用，新的API往往懒得包括文档。看看这个API和替代它的API之间的区别。
至少一年--也许是两年--这些新的重要功能的最好记录都隐藏在标题文件中，这是卑鄙的。
在本周的Under the Rader节目中，我的朋友马可和戴维克继续讲述了马可向斯威夫特和斯威夫特用户界面转变的过程。在这一集中，Marco和Dave都很有说服力地描述了苹果开发者在试图理解如何使用苹果提供的工具时所经历的一些绝对痛苦。
在这篇帖子的底部是他们的想法的文字记录，这是为了让文字更清晰一些而略加删减。如果你想从马的嘴里听，可以在扬声器转换时提供Overcast Timestamp链接。
不管怎样，我已经敲打这个鼓好几年了。我对苹果的问题一无所知。
文档团队是否没有时间对新的API做出反应？(我会买的。)。
文档是否不被视为发货的先决条件？(我肯定会买的。)。
不管是什么问题，都需要解决。这是一个多年来一直在恶化的问题，锅底终于沸腾起来。
Marco：必须学习SwiftUI首先，现有的学习资源仍然很糟糕，因为它是一种非常年轻的语言/框架/思考方法。它太年轻了，而且变化太频繁--类似于SWIFT的早期--以至于很多教程、样例代码或Stack Overflow答案都不再正确了。因为从去年写到现在，有些事情已经改变了。或者答案是在测试版中发布的，甚至在同年之后的测试版中，类的名称发生了变化，或者你应该做某事的方式也发生了变化。现在还为时尚早。
在这个时候，你会真切地感受到我们是多么需要苹果提供更好的文档支持。最棒的事情之一[…]。关于php🤣的一点是php的网站上总是有特别的文档。
在php.net上，你可以搜索任何函数，编辑器会内置热键，所以，在TextMate中，我可以点击⌃H，它会从php.net弹出一个文档窗口，告诉你我当时光标所在的任何函数名。那里一直都有很棒的文档。在文档页上--几乎在语言中的每个函数中都有很多--文档页上有一些示例代码片段。还有评论！因此，即使示例代码不太适合您，或者没有回答您的问题，注释通常也可以。
这是我真的希望苹果的文档能有的东西--这些小小的用法例子--因为它们真的可以帮助解释和展示，而不仅仅是纯粹的API参考，如何做一些事情。或者一个函数是用来做什么的。
随着我们进入SWIFT用户界面领域，结合所有这些更高级别的概念，稍微复杂一点的事情-一旦SWIFT完成了所有的异步/等待操作(大概在一两年后)，这一点也将同样适用。很多这样的概念都很难理解，因为它们太抽象了，它们的名字听起来也很简单，很难知道这是做什么的，如何使用它，所以我们最终都不得不去StackOverflow和教程博客，因为苹果自己的文档-[如果]它甚至在那里，这是一个很大的[如果]--是如此简单和简单，就像乔尼·伊恩(Jony I)设计的那样。
马可：是的，那是一张很大的白纸。这就像，“这个类型只做一件事”，然后就没有其他上下文了；没有任何例子显示“你什么时候会用这个”，“你怎么用这个”，“你是否以某种方式调用它，比如作为一个构造函数”。
您可以从文档页面上的这些小片段中获得如此多的价值，就像PHP所做的那样。比如，“这是一个如何使用这个东西的四行代码的例子”。在我学习这些东西的同时，我也非常希望如此。
我看到了-我可以想象这就是初学者对编程几乎所有部分的看法-因为我在Swift和SwiftUI以及SwiftUI建立在这些概念上是如此的初学者-我正在体验一段时间以来第一次成为初学者的感觉。我将从更好的文档中获益良多，并且--想必是在苹果--做出相当大的努力，不仅要编写文档，而且要随着语言的变化而更新文档。
当你有这些变化很大的年轻语言，或者这些变化很大的年轻框架时，这就是问题所在。如果您依赖于教程博客帖子和StackOverflow答案，那么正如我前面所说，这些内容很快就会过时。在苹果，没有人的全职工作是确保所有这些教程博客帖子可以在语言变化时更新，所以它们大多不会[更新]。或者，有些是，有些不是，很难知道当你找到它的时候，你会落在什么地方。
即便如此，SwiftUI虽然很酷，在过去的一年里也受到了语言书呆子们的高度关注，但仍然很少有关于它的东西，非常非常少。除了微不足道的用例之外，还有更少的东西。例如，如果你必须用SwiftUI做一个技术演示，并且你必须有一个可以改变和递增一个数字的按钮状态，那就太棒了！关于这一点，有一百万篇博客帖子。
但是，一旦它像是，“好的，我怎么把它绑定到应用程序的其余部分呢？”这是一个真正的应用程序，它有实际的需求，比如持久性存储、不同的屏幕等等。一旦你增加了现实世界中应用程序的复杂性，这些教程中的大多数都无法涵盖这一点，或者没有涵盖这一点。所以，戴夫，我花了很长时间，试图从人们或苹果公司在WWDC会议上提供的这些琐碎的小教程中采用SwiftUI，试图真正构建“我如何将其连接到我的数据库中”？“如何将其连接到我的下载器或同步引擎？”已经有太多这样的事情了。我想我终于明白了，但它不是微不足道的，也不是显而易见的，而且有这么多奇怪的小陷阱。
戴夫：不过，我绝对能感受到你的痛苦。这件事让我如此沮丧的是什么[…]。网上绝对有几个非常棒的SwiftUI资源。对我来说，这是保罗·哈德森(Paul Hudson)写的《与斯威夫特一起黑客攻击》。我80%的SwiftUI知识都来自他的网站和视频。[…]。他有一个很棒的过程，他会制作这些视频，向你展示一个超越微不足道的例子的一个层次，在这个例子中，你最终会得到像…这样的东西。琐碎的+。这不是一个成熟的例子，[…]。你所说的那些粗糙的边缘仍然存在。我肯定会继续遇到这种情况。我想做一些比显而易见的事情更多的事情，然后，你就像是从悬崖上跳了下去，就像是“祝你好运”。[…]。
我记得在初春的时候，我记得在苹果社区里有几位教育家。通常在会议巡回会议上发言的人，他们在很多会议上发言，他们举办研讨会，以及教育工作者等。他们说：“你知道吗？看来我们不可能在2020年全年都去旅行了。我们将不能召开会议；我们将不能做很多事情。嘿，苹果，你们社区里有很多非常有才华的教育工作者，他们有很多业余时间。如果你能利用这一点，那将是一件很棒的事情。“。
令人遗憾的是，现在我们已经接近年底了，看起来他们并没有这么做。在这方面似乎没有任何行动，利用所有这些擅长解释事物、创建样例应用程序的人。以一种能帮助你和我这种情况下的人的方式来做这项工作。我真的很同情那些在SwiftUI上没有几十年编程经验的人。如果这是你正在学习的第一个应用程序，从某种程度上来说，它很简单。[…]。一个真正基本的SwiftUI应用程序可能比最基本的UIKit应用程序更容易构建。但是，一旦你开始超越这一点，事情就会变得如此复杂，变得如此之快。
我也在想--文档是如此之难--是如何，最有能力为一个新平台制作文档的人就是这个平台的创建者。因为他们可以编写文档，并在发布过程中提供文档。[…]。我为所有苹果技术教育工作者感到难过，(当)一个新的SDK发布，或者一个新的测试版发布时，然后他们就像是三天不眠不休地疯狂地更新他们的所有东西，获得新的内容。他们做得很好--我很欣赏--但这并不一定非得让人抓狂。
这是可能的，苹果的文档团队几个月来一直在与编写API的人一起工作。在第一天，这里有一组很棒的例子，展示了如何使用它的代码。
你完全正确--特别是关于SwiftUI--它的本质就是传统的文档…。如果你去文档了解SwiftUI中的文本，View，你可以应用于该View的不同修饰符的数量可能有数百个-如果不是更多的话。但是，仅仅列出你可以对一篇文本做的所有事情的巨大清单是没有帮助的。你想看到的是，“好吧，我该怎么做这样的文本呢？”“如果我想要多行文本怎么办？”“如果我想要只有这么多行的多行文本，然后中间对齐怎么办？”做这样的事情，你需要榜样。我不认为人们实际使用的案例总数有那么多。我能感受到你的痛苦。
