25 ms·

Apple Developer Documentation Is Missing

830 points by chriskrycho 7y ago

chooseaname 7y ago
> Apple, if you want developers to love your platform — and you should, because good developers are your lifeblood — and if you don’t want them to flee for other platforms — and you should be worried about that, because the web is everywhere and Microsoft is coming for you — then you need to take this seriously. Adopt the mentality that has served other frameworks and languages so well: If it isn’t documented, it isn’t done. Apple has enough rabid supporters, they can lose the occasional developer to bad docs. Apple doesn't care or need to care. They are arrogant that way. Also, what other platforms? Android? A fair portion of iOS devs are also already Android devs. Look, this is just going to fall on deaf ears. Apple isn't listening. Their machine is output only.
- sillysaurusx 7y ago
  Look, this is just going to fall on deaf ears. Apple isn't listening. Their machine is output only. That's not really true. Apple is active on Twitter and actively reaches out to correct problems. For example, when I complained that their Xcode beta hangs when you open a large file, an Xcode dev reached out to me and asked for a repro case. https://twitter.com/theshawwn/status/1175197286349119490 https://twitter.com/theshawwn/status/1175197286349119490 (I'm not an Apple fanboy, just a dev.)
  - AlexandrB 7y ago
    Isn't that the exception that proves the rule though? Why is Twitter the most effective way to get developer support from Apple as opposed to their own website?
    - 52-6F-62 7y ago
      Yeah. As much as I appreciate their responsiveness on Twitter, it doesn't much help those of us who are not on Twitter. (Tangential rant: I dislike how it seems like the most effective path for anything resembling customer service from many companies is to call them out on Twitter alone. I've written emails to some companies over months to no single response—but to look on their Twitter you'll see an answer within hours, or minutes.)
      - dnautics 7y ago
        That shouldn't be surprising as Twitter is a public forum, so there's more accountability.
        52-6F-62 7y ago
        I'm not surprised. I'm a bit miffed, though. We shouldn't have to shame companies to get a bit of customer service—let alone a response to an email.
      - revscat 7y ago
        I get what you're saying -- that companies should be internally driven to address concerns such as yours -- but I'm starting to shift away from that thinking. We're social apes. We evolved in groups, and respond to group pressures. Responding to public shaming is perhaps a more natural state of things than what we tend to expect. It certainly seems more effective.
        52-6F-62 7y ago
        It's the dirty road, though. In capitalism the market is supposed to correct for bad acting like poor customer service. Instead it's a public haranguing like putting someone in the stocks, except in exponentially less response time.
        sosborn 7y ago
        > In capitalism the market is supposed to correct for bad acting like poor customer service. That only works when the public knows that the customer service experience is poor. I'm no fan of Twitter, but putting this stuff in the open is incredible effective for this reason.
      - Ensorceled 7y ago
        Yes, pretty much every company is this way. I often get a response, support ticket and solution via Twitter before my email/webform request is even processed.
    - Rebelgecko 7y ago
      Reminds me of this post from a few days ago: https://news.ycombinator.com/item?id=21324798 https://news.ycombinator.com/item?id=21324798 tl;dr: Recent performance improvements in the Mac version of Firefox are dependent on an undocumented feature of an API that was tweeted out by someone from Apple
  - _jal 7y ago
    Taking bug reports on Twitter is nice, but not comparable to improving documentation. One is a developer reaching out (costs: developer time, management involvement: granting permission). The other is a change in project plans, staffing, workflow and timelines (costs: large, management involvement: massive).
    - w0utert 7y ago
      >> One is a developer reaching out (costs: developer time, management involvement: granting permission). The other is a change in project plans, staffing, workflow and timelines (costs: large, management involvement: massive). I think it's a pretty safe bet to expect, for this reason alone, that the documentation quality of things like SwiftUI will improve over time. It seems pretty obvious they directed all their efforts to releasing SwiftUI within their iOS 13 release window, which likely meant the API only 'stabilized' very late in the process and it would be impossible to spend time and resources documenting it, at least not without postponing the release (not an option). Generally speaking, in my experience all of the 'established' Apple API's have pretty good documentation. SwiftUI seems rushed, and it would probably been better if they waited until iOS 14 and release it along with documentation. I'm not definding Apple here, but I think the article is overstating how bad their documentation is based on one brand-new API that probably wasn't fully cooked for release to begin with.
  - mpweiher 7y ago
    As far as I can tell, this is individual developers reaching out, possibly at risk violating company policy. They do it anyway, and should be commended, but this isn't Apple per se.
- scarface74 7y ago
  Most developers who are making apps for iOS are working for companies that only care about money. There is no fanaticism about it. If developers optimized for working on platforms they liked, no one would write console games.
  - greggman2 7y ago
    Um, hmmm, that is exactly the opposite of my experience writing console games. Console game dev is fun because you can push the machine to the limit and know every technique you use will work across all devices since they are all the same (or close enough). PC/Mobile dev is hell compared to that. I worked at a company that did mostly console, shipped one PC game, vowed never again as the support costs were several orders of magnitude higher than console.
    - scarface74 7y ago
      Game developers are some of the lowest paid, most highly exploited developers out their.
- WrtCdEvrydy 7y ago
  It's really funny to think about cyclical stuff and see how Blackberry used to treat their developers like shit (with stupid signing keys and stuff) and just look at Apple falling into the same trap.
  - craydandy 7y ago
    And this reminds me of the documentation quality of Symbian around 2005-2007. I would highly recommend the author of the article the check it out, before lamenting Apple's documentation.
    - nullandvoid 7y ago
      I mean it's a discounted OS is it really a comparison? We're talking about one of the biggest platforms in the world here with unlimited money to throw at this problem there is no excuse
      - moron4hire 7y ago
        Seriously, Apple is one of the richest companies in the world (I don't remember if it's still The Richest or not). Similarly, Google's documentation is pretty bad, considering just how ludicrously rich they are. They could afford to hire entire teams whose only jobs were to write documentation and it would barely make a blip in their bottom lines. In contrast, I've always found Microsoft's documentation to be incredible. It can often be hard to find the right thing (though that has getting better, though that might be just my growing experience on how to find things), but they put real, actual effort into documentation. Also, Microsoft has a very strong "corporate style guide" for API design. Every MS API within their major silos is built exactly the same way as every other API. Once you've had some experience with them, it's easy to figure out the others. I find Android to be down-right schizophrenic in comparison. It's one of the many reasons I continue to focus on MS platforms for my work. It's been 20 years since they were the hostile "kill everything that moves" company that people lament.
        mikestew 7y ago
- gatherhunterer 7y ago
  You criticize their rabid fans but aren’t you just as irrational? You have made claims that are so bizarre they cannot be supported by evidence. You are making emotional attacks that sound like someone talking about their high school bully. I don’t know how you convinced yourself that Apple is more interested in being aloof than in making changes that would help them make money but that belief is just as ridiculous as the belief that they are altruistic. “Apple” has become a trigger word for many people. It is strange that one would allow something they claim to dislike to have such a profound impact on them that it compromises their reasoning.
  - chooseaname 7y ago
    Apple has a very long and very known history of ignoring problems until they can't. They'll get away with terrible/missing docs until they can't. > You are making emotional attacks... Am I?
  - Dylan16807 7y ago
    > You have made claims that are so bizarre they cannot be supported by evidence. I, uh, example please? "Apple doesn't need to care" is in no way bizarre.
  - computerex 7y ago
    https://www.engadget.com/2010/06/24/apple-responds-over-iphone-4-reception-issues-youre-holding-th https://www.engadget.com/2010/06/24/apple-responds-over-ipho... https://9to5mac.com/2019/02/11/italian-apple-homepage-to-add-iphone-battery-throttling-advisory/ https://9to5mac.com/2019/02/11/italian-apple-homepage-to-add... https://www.theverge.com/2017/12/28/16827248/apple-iphone-battery-replacement-price-slow-down-apology https://www.theverge.com/2017/12/28/16827248/apple-iphone-ba... https://www.theinquirer.net/inquirer/news/3032188/apple-faces-class-action-lawsuit-over-borked-macbook-keyboards https://www.theinquirer.net/inquirer/news/3032188/apple-face... These is just a very small subset of incidents with Apple where Apple failed to right their wrongs and was ultimately forced to do so by public and or legal pressure. Apple as a company is known for ignoring feedback altogether.
    - 7y ago
travisgriggs 7y ago
I work half and half pretty much maintaining the same app in both iOS and Android. Since the introduction of Swift, the Apple docs have become much terser (it's like Jony Ives slimness fettish got a hold of them). Even with that, they're better (by far) than what I find with the Android docs. The Android docs "explain" very little.
- iainmerrick 7y ago
  Android suffers a lot from quantity over quality. Classes are usually documented, but usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag. Edit to add: I also work on both platforms, and I’d say iOS (along with MacOS) is usually easier to work with because the design tends to be sane and the names are fairly descriptive; whereas Android has a lot of weird and questionable design decisions so it’s harder to guess how things really work. On the upside for Android, it’s often possible to just read the source code (at least for the core OS). I think the docs are about equally bad overall.
  - andybak 7y ago
    > usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag. Ah - the "repeat the method names with spaces in it" style of documentation. This is merely an exaggerated form of a trap that the majority of documentation falls into to some degree - documenting the "what" but neglecting the "why" or "how". It tells you the bit you can easily work out by intuition, reading the source or using your IDE's features. And it leaves out the really important parts: "how should I use this method?" and "why would I need to?" Method based documentation also has problems explaining how API calls are used in concert. Understanding each method in isolation something leaves huge gaps in understanding how they are to be used together. And no - you can't plug the gaps with lazy video tutorials.
    - oefrha 7y ago
      > Ah - the "repeat the method names with spaces in it" style of documentation. That's usually a symptom of aggressive linters enforcing the rule that every single public method must be documented. Programmers then produce useless "documentation" to shut the linters up. Utter waste of disk space.
non-entity 7y ago
I haven't done a lot of work in Apple ecosystems, but what I have seen from their docs are admittedly pretty bad. Recently out of curiosity, I tried to figure out how macOS drivers are written and left more confused than I was before. Microsoft iirc, used to have their docs terribly organized (it was difficult for me to find what I wanted without a Google search) but they seem to have improved that nowadays
- pmjordan 7y ago
  Driver development docs on macOS largely haven't been updated in 10+ years. I started doing macOS kernel stuff when Snow Leopard was the latest release, and the only documentation I can think of since then has been sample code for Audio Server Plugins (for writing new-style audio drivers) and headerdocs explaining the transition from IOUSB* to IOUSBHost* APIs. Any additional information has been buried in a bunch of WWDC session videos, or you have to extract it from Apple by filing DTS incidents. On the other hand, Apple have decided a bunch of documentation was out of date, so they've simply made it harder to access by burying it in archive sections or taking it offline altogether, without providing replacements. Getting into driver development now is almost certainly a lot trickier than it was back then.
  - saagarjha 7y ago
    I hope Apple credited you the DTS incidents back for something like that!
    - pmjordan 7y ago
      They have credited a bunch of DTS incidents back, but that normally only applies where they determine that they either: * can't help you * don't want to help you TBH, compared to the person-hours required to write up the DTS incident in the first place and keep the conversation going, test out their responses, etc., the cost of the incident itself is minimal. Let alone the cost of the times where I decide to go it alone and figure it out by trial & error or reverse engineering…
Amorymeltzer 7y ago
Last week's ATP[1] had a segment on this, in particular a discussion of https://nooverviewavailable.com/ https://nooverviewavailable.com/ which has an estimated breakdown of what percent of each framework has documentation. 1: https://atp.fm/episodes/349 https://atp.fm/episodes/349
- czr 7y ago
  timestamped link: https://overcast.fm/+R7DXB8Hbs/14:08 https://overcast.fm/+R7DXB8Hbs/14:08
macinjosh 7y ago
I am sure all the documentation this guy has ever written has been 100% perfect. /s Calling out other people's work as 'garbage' is pretty shameful. In my experience Apple's documentation is some of the best around. They have sample projects showing you how APIs work, good integration into their IDE, and lots of talks on video about their APIs given by the very engineers that built the thing. Not even to mention their written documentation. This blog post offers no evidence or specifics as to what makes it 'garbage'.
- ebg13 7y ago
  > Calling out other people's work as 'garbage' is pretty shameful Apple is not a people. Apple is a TRILLION dollar megacorp. They can afford more.
  - macinjosh 7y ago
    Yeah... but you do know that Apple is comprised of actual real people like you and me though, right?
    - jk563 7y ago
      And the author acknowledges that those individuals are not the problem. > the problem is not individual engineers — who are not responsible for writing docs; that is the responsibility of dedicated coumentation teams. But that does not make it any less a failure of Apple’s engineering organization.
      - fireattack 7y ago
        I get author's point, but this sentence reads weird. If a team ("dedicated [documentation team]") is responsible for something, surely the individuals in such team are responsible too? Or the author is making a distinction between "engineers" and team members of documentation teams?
        chriskrycho 7y ago
tempodox 7y ago
Apple's developer docs have been incomplete since the introduction of OS X. I don't expect it to get any better before hell freezes over. The article mentions that this makes it hard for newbies to learn. That's true but my guess is that by the time those chickens come home to roost, JavaScript will be called a systems programming language. Edit: Updated wording to article's title change.
- iainmerrick 7y ago
  I wouldn’t put it quite as strongly as that, but yes, the OS X docs have never been great. It’s a shame, because the classic MacOS docs were amazing, amongst the best technical docs of all time at their peak. (I had a shelf of Inside Mac books, and they were useful for years.)
- pier25 7y ago
  Trying to learn Cocoa dev in 2019 is very frustrating. Not only there are practically no updated resources available (books, courses, etc), but the Apple docs are really lackluster. At first I thought Catalyst was about empowering Cocoa devs to bring Mac apps into iOS, but now I see it's just the opposite. I imagine the number of macOS devs has been slowly shrinking over the years.
gigatexal 7y ago
According to Marco of overcast and the ATP podcast fame the docs pertaining to the audio subsystem is really lacking.
oflannabhra 7y ago
A couple years ago, maybe around Swift's debut, Apple began to mark all their sample code, projects, programming guides, technical notes, etc, as deprecated and unmaintained with a header on each page stating so, and putting it all in their "Documentation Archive" [0] They've had a new push to make sure that the remaining official documentation is available in either Swift or Objective-C, but I have yet to see any attempt at migrating some of their best documentation: CoreBluetooth Programming Guide, CoreImage Programming Guide, or CoreData Programming Guide [1]. These are hugely helpful documents that take a much higher level approach than just API documentation and get to the heart of the design of a framework, with helpful diagrams, etc. I understand that Apple has a huge body of work regarding documentation, and that it would be unfair for us to require them to never deprecate any of their documentation, but at this point, we basically have header files, documents automatically generated by header files, with several large swatch of that even being undocumented [2]. I do think that Apple made a huge effort with SwiftUI to provide meaningful, helpful documentation at the time of the announcement [3], and I don't want that to get lost in the discussion. Unfortunately the framework has iterated so quickly that much of it is out of date. However, when Xamarin [4] independently documents some of Apple's APIs better than Apple does... it is indeed time for a call to action. This is especially sad because Apple used to have some of the best documentation ever available. I basically learned how to program through using their documentation. [0] - https://developer.apple.com/library/archive/navigation/ https://developer.apple.com/library/archive/navigation/ [1] - https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/CoreData/index.html#//apple_ref/doc/uid/TP40001075 https://developer.apple.com/library/archive/documentation/Co... [2] - https://nooverviewavailable.com https://nooverviewavailable.com [3] - https://developer.apple.com/documentation/swiftui https://developer.apple.com/documentation/swiftui [4] - https://twitter.com/akashivskyy/status/1187790245804367873 https://twitter.com/akashivskyy/status/1187790245804367873
- protomyth 7y ago
  Along with this, they removed or not generated PDFs like they once had. This is really painful for folks that have problems with looking at a screen for an extended period. They don't even have downloadable documentation that can be read on an iPad. The lack of PDF is a real issue for me. The continued failing of example code is really painful.
boris 7y ago
Their diagnostics is pretty cool, though. How about this gem: ld: warning: ignoring file build2/libb.u.a, building for macOS-x86_64 but attempting to link with file built for unknown-unsupported file format Going to steal that "unknown-unsupported" term for sure.
deleted 7y ago
[deleted]
supernes 7y ago
Developer goodwill is not really that essential to a lifestyle accessories brand.
- scarface74 7y ago
  Right because 50% of the US mobile market only buys a phone because it’s an “accessory”.
  - wetpaws 7y ago
    Not sure if it is a sarcasm or not.
    - scarface74 7y ago
      Of course it’s sarcasm. It’s just like people who sat that the iPhone is a “status symbol”. How can something be a status symbol when 50% of smart phone users have it in the US and that anyone on any of the four major carriers can buy one an interest free 24 month loan. Geeks can’t stand to face the fact that people who can afford to have a choice, overwhelmingly shy away from Android.
      - orangecat 7y ago
        How can something be a status symbol when 50% of smart phone users have it in the US It's more that Apple has gotten people to view anything other than the iPhone as low status, e.g. green bubbles.
        scarface74 7y ago
        So Apple has brainwasheded people for 20 years? Geeks have been saying that Apple was a status symbol since the iPod. As far as iMessage, it couldn't possibly be that Google has had four or five failed attempts at a messaging platform?
        askafriend 7y ago
Phillips126 7y ago
Docs are always something I evaluate before moving forward with a specific tool or language for a project. I have not done much work in the Apple ecosystem but it surprises me that a company of this size would have lackluster docs. It makes me wonder how many non-Apple developers give up on their idea for an app due to frustration and how that translates to lost profit for Apple given their 30% cut. I am not a huge Golang fan but recently I found myself using Go quite a bit and I really appreciate their docs which include a description of each function and an example. The example code is even editable with a "Run" button so you could test and understand the function much better before moving it to your own code. Here's an example if you are unfamiliar with Golang docs (click the "example" link for the editable code): https://golang.org/pkg/strings/#Compare https://golang.org/pkg/strings/#Compare
cyberferret 7y ago
Still? It has been a while since I have done any Apple platform specific native development, but I remember about 5 or 6 years ago writing an iOS and OS X app for communicating with an audio modelling device, and the documentation for CoreMIDI was woefully lacking. I couldn't believe that a part of the Apple operating systems that had been ingrained for years had so little documentation and examples at that time. I ended up finding out more from a lot of third party blogs and via forums. I haven't checked, but are things like the MIDI framework still badly documented in the Swift docs?
- AlanYx 7y ago
  >I haven't checked, but are things like the MIDI framework still badly documented in the Swift docs? Documentation for the entire audio stack has actually gotten quite a bit worse. Many references have been removed without new replacements being provided. In many cases, there are broken links in what little documentation remains. (For example, TN2274, which describes the USB audio stack is still around, but several of the outgoing links, for example the documentation for developing a USB audio plugin, are now broken, with the sample code deprecated and removed with no replacement.) New frameworks like AVAudioEngine simply don't document important limitations, particularly for OS X. The Core Audio mailing list used to be a good place to get help and answers in cases where the documentation is weak, but traffic has withered and no from Apple seems to reply to messages any more. There has been a total of only four messages on the mailing list this month. It's really a shame, because the audio stack is well-designed, but the documentation is so poor except for the basics that newcomers would have difficulty getting anything tricky off the ground.
  - tonynguyen1 7y ago
    This is so true. Audio APis are poorly documented. I have only done my task by customizing examples :).
  - WWLink 7y ago
    I wonder if the people who worked on it don't work there anymore.
  - 7y ago
jrochkind1 7y ago
15+ years ago, Apple had some of the BEST documentation. But I agree it's fallen precipitously.
- Ididntdothis 7y ago
  I worked a little on the Mac in the 90s and then their documentation was really good. You could read it like a book. Actually Microsoft was really good back then too with the MSDN library CDs they shipped. Not it’s pretty bad and getting worse all the time with a lot of broken links and tons of auto generated content that doesn’t explain the big picture.
deleted 7y ago
[deleted]
balls187 7y ago
My issue with this is that the developer is comparing his experience with Apple's documentation over a few months, with his anecdotal experience over 4 years. Part of gaining experience with a platform is the ability to source answers to technical questions effectively, including how to use official documentation effectively.
- chriskrycho 7y ago
  I'm extremely comfortable reading documentation for a very wide variety of platforms, languages, etc. (The first software I ever wrote was Fortran via `gfortran`. Trial by fire!) It's not just me. This is just straight-up absent: https://nooverviewavailable.com/swiftui/ https://nooverviewavailable.com/swiftui/ As I noted in the post, I'm getting by anyway… but it's more work than it needs to be, and more work/worse state of docs than other ecosystems I've learned in similar amounts of time.
  - balls187 7y ago
    My comment wasn't about your comfort level. It was about comparing your experience 4 months in, to your experience 4 years in, anecdotally.
    - chriskrycho 7y ago
      Erm, yes. Any possible comparison anyone could do of their own experiences would by definition be anecdotal. I also know exactly what my first 4 months in other ecosystems were like. Including picking up Fortran! That was rough! :)
no_wizard 7y ago
I actually agree whole heartedly with the intentions behind this article. I find Apples documentation to be incomplete and not nearly as detailed as I think it should be. I think that personally it’s not all that well organized either. My minimum standard for good documentation has and always been Python’s[0]. While no documentation is perfect, I think they mostly get it right by providing good explanations and examples consistently throughout the documentation. I also like how it’s spilt up between modules and the code examples are routinely updated. I have found very little issue with Python’s docs. While it could definitely use more examples and and deeper content around asyncio in some parts (mostly around transports and protocols) on the whole its very good, to me it’s what all organizations should strive for at a minimum. I also want to call put Mozilla’s Developer Network (MDN)[1] as stellar, I reference and use it all the time and have genuinely been happy with it. To be fair in assessments, I’ve also found links in Microsoft’s documentation that often link to things they have already marked as outdated or not going to be updated, or just don’t work like the GitHub links on this page: https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/controls/views?WT.mc_id=docs-dotnet-xamarin https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-... So I think a lot of documentation around the big platforms especially have a lot of work to do. This isn’t to say documentation is easy though. I sincerely hope that all this noise just means it becomes more of a priority. I know from experience that writing good documentation is hard and I don’t want this to come across like I’m faulting anyone in particular or organization in particular. I imagine with large and ever changing platforms it’s quite the challenge. I just wanted to point to some examples I believe get it right most of the time. [0]https://docs.python.org/3/ https://docs.python.org/3/ [1]https://developer.mozilla.org/en-US/ https://developer.mozilla.org/en-US/
- not_a_cop75 7y ago
  php, whether you like the language, or abhor it, has always had some of the most useful documentation, I've found.
  - richardwhiuk 7y ago
    I disagree. See Example 5 in https://www.php.net/manual/en/security.database.sql-injection.php https://www.php.net/manual/en/security.database.sql-injectio... This is the recommended way to avoid SQL injection, using sprintf...
jmull 7y ago
The Swift language has excellent documentation. For SwiftUI, the WWDC presentations are essential, IMO, for the high-level stuff. There is basic reference documentation, but there's no way to put it all together without a high-level understanding. It follows the patterns of some other frameworks so depending on your experience you may be able to get by without the WWDC presentations, but I'd still watch them or at least read the transcripts. I think Swift Package Manager is meant as a community tool, and the love and care it needs to become excellent is not going to be coming from Apple, not without some kind of strategic change. Either the community will value it and figure out how to move it forward or it's not going to get much better. I could be wrong -- I'm trying to judge it's on-going strategic importance to Apple -- but I think the way it's going to improve is through community involvement. Anyway, I'm not sure what the point of this kind of rant is. Whining about Apple is an easy way to get useless internet karma points, but it's such a bad look for a developer. At least half the job is being the one who finally deals with things someone else probably should have already dealt with but didn't.
- andybak 7y ago
  > For SwiftUI, the WWDC presentations are essential, Are these videos, slides and transcripts? I do hope not because none of those things are documentation by any reasonable definition.
  - jmull 7y ago
    They are. I definitely don't think it's an ideal form. The content itself is high-quality, but I'd much prefer a well-written document. I point it out because if you want to learn SwiftUI your best approach is probably to start with the presentations, whether you like that form or not. Many will naturally avoid that kind of content and I'm trying to communicate that in this case you really should use the presentations.
- chriskrycho 7y ago
  Noted the first two bits in the post. Did you read it? :) As far as SPM goes: they've got it built into Xcode at this point, and are doing WWDC sessions about it. At what point does it become "official" enough to warrant "This needs to be better" criticism? As far as "useless internet karma points": I couldn't care less. History has shown that when people make enough stink about this kind of thing, it sometimes—rarely, but sometimes—gets to the ears of people high enough in the management chain that it ends up shaking things loose at the mid-level spots where poor decisions around these things tend to get made. I don't work at Apple. I can't go fix most of this stuff. In my day job, I spend a lot of time on these kinds of concerns. In this context, though, the only thing I can do is shout a bit and hope it shakes things up a bit.
fortran77 7y ago
It's always been bad, too! Back in the OS9 days, the Apple documentation was "cumulative". You had to know every trick, every hidden bit and flag, back to day 1 in order to write a program. It's no better today. People who live isolated in the Mac universe have no idea how good Microsoft Visual Studio tools are, and how complete and thorough the documentation is, and how consistent the API is. You don't have to wade through a 30 years of legacy APIs to get anything done.
- heisenbit 7y ago
  Woz documented every line of his Apple ][ system monitor code and it was a joy to read.
  - fortran77 7y ago
    Yes! I've been around since those days.
ChrisMarshallNY 7y ago
Some time ago, I was contacted by Apple to apply for a job. My code is insanely well-documented. I like to think that a lot of the inspiration for my code docs comes from Apple's open codebases. Their code is exceptionally well-documented. In any case, as is usual with all employers, these days, they completely ignored the focused, relevant links that I sent them to elements of my extensive portfolio of repos, and, instead, based the entire interview on a 50-line binary tree test in Swift. I'll make it clear that I'm NOT a fan of these. I am mediocre, at best, at them, as I don't come from a traditional CS background (I started as an EE). In any case, during the test, I did what I always do when I write code. I stopped to write a header document for the function. This was clearly not something the tester liked. Also, to add insult to injury, they dinged me for not writing a cascaded nil-coalescing operator. The code they wanted me to write was difficult to understand, and absolutely not one bit faster. What makes this even funnier, was that this was for an Objective-C job, and the links that I sent them (that they ignored), were to ObjC repos. After that, I just gave up on them. It kind of shows where a lot of this is coming from. Dynamically-generated documentation can be great (It's clear that the lions' share of Apple's developer documentation is dynamically-generated), but it requires a VERY disciplined coding approach. I suspect that they may be hiring less-disciplined engineers, these days.
- jtchang 7y ago
  What is a "cascaded nil-coalescing operator" ?
  - omaranto 7y ago
    Something like a.?b.?c which is syntactic sugar for: a && a.b && a.b.c (with a short-circuiting &&.)
    - rimliu 7y ago
      This is just optionals chaining, not nil coalescing.
      - 7y ago
mlang23 7y ago
One Cook can ruin many meals.
butuzov 7y ago
This comment has nothing to do with apple, but about documentation in general. I was trying to get into Kubernetes world via kubeflow, a machine learning platform that works on top of the Kubernetes. Well, I have run into a bunch of the missing examples, outdated articles, and things that just don't work (all of that in official documentation). I decide to change this a bit and start working on a small tool [1] that can help check documentation (at least reduce deadlinks in the documentation, when someone moves git files or just original source of info dies). Since I start working on it, I meet only one project without issues, all others.. well, they all had issues. Maybe one day I post it on HN as a standalone link, but now here we go [1] [1] https://github.com/butuzov/deadlinks/tree/develop https://github.com/butuzov/deadlinks/tree/develop
coldcode 7y ago
I've spent most of my programming life doing Apple stuff (in between Java and C++ non Apple stuff too) and the only really good docs they ever had was the old paper Inside Macintosh in the 80's. Even when I worked at Apple at DTS in the mid 90's we had to hire someone to go around to every engineering dept and find out wtf they just shipped to provide developers something, anything, as documentation. That was back when Apple lost tons of money. Now the excuse can't be financial. Maybe they don't care enough?
edw 7y ago
Nowhere in the comments thus far has anyone pointed out that SwiftUI — the framework in TFA's crosshairs — is in beta. I've written a relatively large amount of SwiftUI code and I get the impression that the design is still in flux. There are corner cases (as well as much more mainstream one) that haven't been fully thought through. Beta 5 of Xcode 11 brought non-trivial changes to the API and I expect those to continue. "It's not finished until it's documented" is a fine sentiment, but I don't think Apple has remotely claimed that SwiftUI is finished.
- oflannabhra 7y ago
  As I noted in another comment, the documentation for SwiftUI is actually pretty good, especially if you take into account how quickly the framework has changed. It includes some rich, progressive tutorials. [0] The author states that they are planning to write an app from scratch with SwiftUI. I think most iOS developers would hesitate to build an entire app on a beta framework. [0] - https://developer.apple.com/tutorials/swiftui/tutorials https://developer.apple.com/tutorials/swiftui/tutorials
  - mistahenry 7y ago
    They would also hesitate to build an app that only works in iOS 13+ when iOS 13 is the current iOS
  - chriskrycho 7y ago
    These tutorials are great (when they're working! That's been a bit spotty)—genuinely great. But they don't make up for everything that isn't present. Take a step off that beaten path and you're in for a world of pain today.
  - varenc 7y ago
    The SwiftUI tutorials also have quiz questions at the bottom to test your understanding of the tutorial. Never seen that before but seems like a great idea https://developer.apple.com/tutorials/swiftui/creating-and-combining-views#check-your-understanding https://developer.apple.com/tutorials/swiftui/creating-and-c...
meh206 7y ago
They're too big to care.
mmusson 7y ago
When I first learned iOS ten years ago I thought the documentation was outstanding. It had good API level documentation as well as a large number of guides that showed the right way to use the API to implement particular features. I recently returned to the platform and my experience is very much like the parents. The documentation appears to be almost completely missing. The built-in documentation does not appear to include any guides at all. The API documentation is largely the kind where the description is a more verbose form of the method name, and sometimes when Objective-C is selected the documentation is showing the Swift version.
- mmusson 7y ago
  I have discovered that the previous documentation is still available in a “documentation archive” complete with banner warnings about how it is out of date and unsupported. It is almost impossible to find topics except by using google search. Newer functionality is missing and some of it is no longer accurate, but it is better than nothing.
  - topherPedersen 7y ago
    I've had to resort to referencing the documentation archive before as well. While the new docs are certainly prettier, the old docs were much more substantive.
gnachman 7y ago
The comments in header files are often the only (or only useful) documentation. So don’t give up before looking there. Sometimes they wait a few years to write docs. For example, NSWindowAccessoryViewController went undocumented for three or four years. Which was fine because it was too buggy for me to use anyway. The docs are enough to get you started but it’s only brutal experience that teaches you how to use things. In practice you spend a lot of time working around bugs and design flaws. Those will never be documented, of course.
- WWLink 7y ago
  Yeah, I developed software for a platform that isn't documented anywhere at all on the internet, and the documentation it comes with is sketchy. Discovering a new widget and spending time messing around with it was the norm.
Shank 7y ago
Maybe I'm the only one, but when I start looking into a project, I start at the API docs and work from there. I really need to know if key features I want are viable on the platform or not. If I want to use an accessibility API to, in a supported way, read all of the items in every menu in the menu bar, how do I do that? Is it supported? Is there a set of best practices I should follow? The problem with not documenting things is that developers like me are turned off before we start. I don't want to bend the platform so far that it breaks. I want the limits. I'm tired of reading stories about apps being pulled for using private APIs, or breaking in future versions because they're removed. I want to do things in a supported way so I can make everyone happy. Right now, I can't even see the boundaries of what's possible, because nothing is documented. I don't even want to try to write for Apple platforms, because it's entirely inscrutable and unpredictable.
- bob1029 7y ago
  You are not the only one. My most recent experience with Apple's documentation (regarding some iOS 13 API concern), left me with a sense of impending doom and hopelessness. After about 5 minutes I gave up and went back to playing the google/stackoverflow search game. I have become very addicted to the quality of Microsoft's documentation for things like .Net Core & C#, and have found it virtually impossible to tolerate reading documentation from any other vendor at this point. A completely arbitrary but hopefully obvious side-by-side comparison: Exhibit A: https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.distinct?view=netcore-3.0 https://docs.microsoft.com/en-us/dotnet/api/system.linq.enum... Exhibit B: https://developer.apple.com/documentation/coreimage/cicolor/1438084-init https://developer.apple.com/documentation/coreimage/cicolor/...
  - lilyball 7y ago
    It's unclear to me what you think Exhibit B is demonstrating. That's the documentation for CIColor.init(red:green:blue:alpha:), and it's documented. It creates a CIColor with the specified red/green/blue/alpha components. This is literally just a model object.
    - 7y ago
perfectstorm 7y ago
So much this. The other day i was trying to look up documentation for Swift’s KVO and i couldn’t find one. I know there’s a KVO API that accepts a closure but i just couldn’t find where it is. smh. Apple used to link sample code with pretty much all the big APIs but they no longer do that. If you want to see how an API is used or see the best practices you’re better off checking stackoverflow.
- Austin_Conlon 7y ago
  When I learned that you could filter by sample code in the bottom left search box of Xcode's documentation window, it made sample code a lot more discoverable for me. Of course that's far from ideal though, and they should be linking to sample code more in the documentation.
- saagarjha 7y ago
  You're looking for NSObject.observe(_:options:changeHandler:), which doesn't seem to have a dedicated documentation page that I can find but it's mentioned here: https://developer.apple.com/documentation/swift/cocoa_design_patterns/using_key-value_observing_in_swift https://developer.apple.com/documentation/swift/cocoa_design...
CalChris 7y ago
For a company with a capitalization of $1.123T, yeah, Apple is pretty cheap on the developer documentation.
rubyn00bie 7y ago
It's funny to read this and have it compared to Ember's docs, especially since I've been using Chris's site a fair bit over the past few months... I only bring this up for posterity, but Ember's documentation is terrible, and what is even worse is the Typescript documentation is almost unusable its so outdated. Chris's site is the only place you can go to find anything and it's incredibly difficult to make sense of or is already completely outdated... There are constant gotchas and missing documentation or things that are flat out wrong... I can understand complaining some about Swift's docs (though I've never had that problem), but comparing them to Ember's seems like an awfully bad take. P.S. I love Ember, learning it has just been nightmarish at points for almost no reason.
- chriskrycho 7y ago
  1. You should file issues against Ember's docs! We have different experiences of it for sure. Even just as experience reports, I know the folks who work on it would love that. 2. The Ember TS stuff is in need of an update—desperately—as are my (several-years-old-now!) blog posts. Unfortunately (unlike Apple) none of those of us who work on it get paid to do so at the moment – at all, including docs. I'd love it if you opened issues against the ember-cli-typescript repo about specific issues/confusions you've had.
  - rubyn00bie 7y ago
    1. Totally, I have, will do more, and would like to... One big difficulty I've had, because I want to fix things (like docs), is because everything post 3.12 is geared towards Octane and those docs are all quite a bit different than everything before it... (and I'm on 3.12) it makes finding the code to change, text, blob pretty difficult (IMHO) since master is mostly Octane. 2. I know you aren't paid and you're a saint for all you've contributed! You've helped me an insane amount, and I want to say "thank you," for it. I wasn't trying to give you too much shit, I just thought it was a little funny... Ember's docs are in disarray for a new language and design patterns, and so are Swifts! ;) I probably should've used a softer word than "awful," my apologies. 2.1 I'll see you in your issue tracker later today :) Thanks for being friendly! I super appreciate it, and for letting me know about it being cool opening those kinds of issues. A LOT of Github repos are hostile to _any_ questions at all (i.e. "go to stackoverflow or take a hike"); so, I tend to not make issues and only PRs.
lasermike026 7y ago
If there is a problem with Apple documentation issue a bug report. I'm not from apple but I worked in their ecosystem for some time. When you experience real problems your manager or CTO might have to get in touch with a managing director. If you go to WWDC make sure you complain directly to the guys wearing the checkered shirts. They are the ones in change. The cool thing about WWDC is that you can communicate directly with Apple developers. They will even look at your code to help.
- saagarjha 7y ago
  > When you experience real problems your manager or CTO might have to get in touch with a managing director. If you can… > If you go to WWDC Again, if you can…
russellbeattie 7y ago
Every once in a while I think to myself, "I have a problem with OSX, I think I'll try to automate it with JavaScript for Automation (JXA)..." You know the rest. The astounding lack of documentation is almost amusing. It becomes an adventure of trying to convert old AppleScript examples into JS, spelunking into GitHub and StackOverflow and general trial and error until I get something to work. All this said, I'd rather have functionality without documentation, than the extreme of not launching an API without proper docs. The solution of course - though Apple would never do this as it's not in their DNA - is to let devs add to their docs like PHP does. I'd be happy to add back a few examples to their site once I figured things out if that option was available to me, but right now there's really no central place for this besides random forums or starting my own repo.
- saagarjha 7y ago
  Nobody seems to use JXA, unlike some of the technologies that are heavily used but just as undocumented :(
  - russellbeattie 7y ago
    I don't disagree, but you might be confusing the chicken and egg. Maybe if Apple actually documented JXA... (it's actually quite useful).
    - saagarjha 7y ago
      I know it is, but I have little hope that it ever will. Everything I've heard points towards the OSA team not doing so hot these days.
strictfp 7y ago
Apple payments APIs are the worst APIs I've ever worked with. They're inconsistent, badly documented, have unannounced breaking changes and contain so many gotchas it isn't funny. For example, some of the most relevant data is attached to the response but isn't officially supported and may or may not be correct. It's not exactly fun to code up payment integrations, and so I was kind of hoping to get it over and done with. But with Apples payment APIs, we needed months of production data to figure out how to use them without shooting ourselves in the foot. Using the API felt like interfacing with some badly configured eventually consistent MongoDB cluster that a bunch of juniors stuffed full of receipts, using the entirely wrong data model.
- kalleboo 7y ago
  And what's worse is the "sandbox" for testing behaves completely different from the real store, and has random undocumented downtime and bugs that you only find out about from other people reporting it on the developer forums. And creating, logging in to, and keeping sandbox accounts from contaminating your real devices is also a PITA.
hugey010 7y ago
I've developed native iOS and Android apps professionally since 2012 and I always found their docs to be a mix of amazing - https://developer.apple.com/design/human-interface-guidelines/ https://developer.apple.com/design/human-interface-guideline..., and fairly useless - https://developer.apple.com/documentation/vision https://developer.apple.com/documentation/vision. All example code I've seen provided by Apple looks like a Fisher-Price® My First UIViewController toy. It is my belief that the Apple iOS docs are just another barrier to developer entry; similar to their $100 yearly license, expensive hardware combined with their WYSINWYG simulator, and woeful iTunesConnect experience. These barriers to entry, including the poor documentation, definitely have some interesting affects on the ecosystem. I've seen examples of all of these in the real world. * Experienced iOS devs have a shared trial by fire experience. * iOS salaries are slightly higher on average compared to Android. * Skilled iOS devs tend to be excellent developers in general. * Average iOS devs can be more arrogant and less likely, or less capable, of helping out in other languages and projects. (Apple framework specialist pigeonhole principle) * There is almost zero culture or standards regarding application architecture or documenting iOS apps. * Underlying "older" concepts like memory management have been masked, forgotten, and / or ignored.
oh_hello 7y ago
Apple's developer guides were amazing. I was able to read through them and become a proficient iOS developer. They are now archived and not updated. Even with experience on the platform, I now often find it hard to navigate the docs and learn major new frameworks. It is a real shame.
thfc06 7y ago
This is exactly what I've been dealing with for the last month, as I attempt to completely re-write an Electron app in Swift. The part about scavenging through WWDC transcripts particularly resonated with me. Coming from JS ecosystem, I was also shocked at how few google results (even stack overflow) would come up for issues I was running into.
- rayascott 7y ago
  What annoys me about Apple, is that clearly their time is valuable to them, but us paying Developer Program members are forced to waste days worth of business hours hunting through their appallingly maintained "documentation". And that really pisses me off.
microtherion 7y ago
OPs criticism is definitely justified, and it makes me sad. In my opinion, the peak of Apple documentation was the new, refactored edition of "Inside Macintosh" in the 1990s: https://en.wikipedia.org/wiki/Inside_Macintosh https://en.wikipedia.org/wiki/Inside_Macintosh Not only is there not enough information, but the documentation team goes out of their way to reorganize what documentation exists every couple of years, so outside links into the docs constantly go stale.
carapace 7y ago
Funny meme on the wall at Google: Picture of Governor Tarkin on the Death Star captioned, "Documentation? At our moment of triumph?" Still makes me laugh.
ngcc_hk 7y ago
Reading hundred comments and the op is about the lack of documentation. Swift is a good language to learn but api no. The discussion might explain it. But should there be one to address that issue as an ecosystem. For example ask Apple to do something and let them sort that out using their employee. Or some web site (I use one particular to help me). Swift is a language like lisp or clojure. You may look at its architecture etc to see whether it is built in issue (lisp is easy but its library is not, say). Or it is really just a hiring issue. Or may I just ask how to address the original question if it is just language lack of good doc.
novok 7y ago
Apple under invests in developer tooling relative to what it does. The dev tooling teams are surprisingly small and the internal dev experience at apple for their own employees is pretty bad compared to other large tech companies. My guess partly is because of the siloed nature of the company, and they don't sell dev tooling for "money".
jariel 7y ago
Absolutely true: if it's not well documented, it's not a product, it's borderline useless. Apple is just one of many 'big companies' that strangely under-document so many products, frankly it's bizarre. If you don't have good docs, tutorials and snippets, it's not 'done'. iOS, Qt, many frameworks: spending days, sometimes literally weeks writing 'tiny experiment code' to navigate the ambiguities or missing parts of docs, it feels totally unacceptable to have to do this. This is a hugely important statement the author is making.
OliverJones 7y ago
Agreed this is a big problem. Sometimes sitting through a WDC tutorial video can unearth answers. But, really? You know, they could call Tim O'Reilly and commission a bunch of excellent books. They have the money and Tim has the writers.
TheKarateKid 7y ago
I’m surprised no one has complained about the lack of documentation for Safari, especially on iOS where special behavior is done for mobile. The best I could find from Apple was several years old, and clearly not up to date as the behavior no longer functioned as documented.
- pier25 7y ago
  Indeed. Stuff like the strange behaviour of <iframe> on iOS is not documented anywhere but StackOverflow or WebKit's bugzilla. For those that don't know, you can't set the height and width of an <iframe> on iOS. Something which has been possible in all browsers since the tag exists.
- saagarjha 7y ago
  There is this: https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/Introduction/Introduction.html#//apple_ref/doc/uid/TP40002051-CH1-SW1 https://developer.apple.com/library/archive/documentation/Ap.... Not sure if this has what you'd need.
  - TheKarateKid 7y ago
    Came across that, but it's terribly outdated. Bottom of the page even says last updated in 2016.
danielinoa 7y ago
Funny thing is Microsoft has much better documentation on Apple's very own frameworks. Simply compare their documentation on this arbitrary type (CIAffineClamp): Microsoft's Documentation: - https://docs.microsoft.com/en-us/dotnet/api/coreimage.ciaffineclamp?view=xamarin-ios-sdk-12 https://docs.microsoft.com/en-us/dotnet/api/coreimage.ciaffi... - https://docs.microsoft.com/en-us/dotnet/api/coreimage.ciaffineclamp.-ctor?view=xamarin-ios-sdk-12 https://docs.microsoft.com/en-us/dotnet/api/coreimage.ciaffi... Apple's Documentation: - https://developer.apple.com/library/archive/documentation/GraphicsImaging/Reference/CoreImageFilterReference/index.html#//apple_ref/doc/filter/ci/CIAffineClamp https://developer.apple.com/library/archive/documentation/Gr...
devin 7y ago
As someone who has only recently gotten into producing an app for iOS, I was immediately struck by the lack and quality of the docs. It’s nice to hear that I’m not alone. The lack of documentation led me to feeling like I was just somehow personally missing something. I’ve been at this for awhile and the apple docs left me feeling like a junior programmer all over again. I wanted to first blame myself, but it’s become clearer to me that Apple just doesn’t care about supporting devs. That’s the theme for years now and it only seems to be getting worse. Bummer.
rasta78 7y ago
It's unclear to me how this post made to the top when it references SwiftUI - a framework which is still in beta and shouldn't even be brought into discussion. On the other hand, UIKit is documented about ~90% which is an insane amount and this is what most of the iOS devs are using on a day-to-day basis.
catchmeifyoucan 7y ago
Might just be me - but I'm attracted to well formatted docs. It's not a dealbreaker but I do appreciate when the fonts, spacing and code snippets are well thought out
specialist 7y ago
Sample code (showing usages) and tests are also part of the documentation.
smacktoward 7y ago
Apple's just doing with documentation what they do with everything else: making it thinner at all costs.

830 points by chriskrycho 7y ago

> Apple, if you want developers to love your platform — and you should, because good developers are your lifeblood — and if you don’t want them to flee for other platforms — and you should be worried about that, because the web is everywhere and Microsoft is coming for you — then you need to take this seriously. Adopt the mentality that has served other frameworks and languages so well: If it isn’t documented, it isn’t done. Apple has enough rabid supporters, they can lose the occasional developer to bad docs. Apple doesn't care or need to care. They are arrogant that way. Also, what other platforms? Android? A fair portion of iOS devs are also already Android devs. Look, this is just going to fall on deaf ears. Apple isn't listening. Their machine is output only.

sillysaurusx 7y ago
Look, this is just going to fall on deaf ears. Apple isn't listening. Their machine is output only. That's not really true. Apple is active on Twitter and actively reaches out to correct problems. For example, when I complained that their Xcode beta hangs when you open a large file, an Xcode dev reached out to me and asked for a repro case. https://twitter.com/theshawwn/status/1175197286349119490 https://twitter.com/theshawwn/status/1175197286349119490 (I'm not an Apple fanboy, just a dev.)
- AlexandrB 7y ago
  Isn't that the exception that proves the rule though? Why is Twitter the most effective way to get developer support from Apple as opposed to their own website?
  - 52-6F-62 7y ago
    Yeah. As much as I appreciate their responsiveness on Twitter, it doesn't much help those of us who are not on Twitter. (Tangential rant: I dislike how it seems like the most effective path for anything resembling customer service from many companies is to call them out on Twitter alone. I've written emails to some companies over months to no single response—but to look on their Twitter you'll see an answer within hours, or minutes.)
    - dnautics 7y ago
      That shouldn't be surprising as Twitter is a public forum, so there's more accountability.
      - 52-6F-62 7y ago
        I'm not surprised. I'm a bit miffed, though. We shouldn't have to shame companies to get a bit of customer service—let alone a response to an email.
    - revscat 7y ago
      I get what you're saying -- that companies should be internally driven to address concerns such as yours -- but I'm starting to shift away from that thinking. We're social apes. We evolved in groups, and respond to group pressures. Responding to public shaming is perhaps a more natural state of things than what we tend to expect. It certainly seems more effective.
      - 52-6F-62 7y ago
        It's the dirty road, though. In capitalism the market is supposed to correct for bad acting like poor customer service. Instead it's a public haranguing like putting someone in the stocks, except in exponentially less response time.
        sosborn 7y ago
        > In capitalism the market is supposed to correct for bad acting like poor customer service. That only works when the public knows that the customer service experience is poor. I'm no fan of Twitter, but putting this stuff in the open is incredible effective for this reason.
    - Ensorceled 7y ago
      Yes, pretty much every company is this way. I often get a response, support ticket and solution via Twitter before my email/webform request is even processed.
  - Rebelgecko 7y ago
    Reminds me of this post from a few days ago: https://news.ycombinator.com/item?id=21324798 https://news.ycombinator.com/item?id=21324798 tl;dr: Recent performance improvements in the Mac version of Firefox are dependent on an undocumented feature of an API that was tweeted out by someone from Apple
- _jal 7y ago
  Taking bug reports on Twitter is nice, but not comparable to improving documentation. One is a developer reaching out (costs: developer time, management involvement: granting permission). The other is a change in project plans, staffing, workflow and timelines (costs: large, management involvement: massive).
  - w0utert 7y ago
    >> One is a developer reaching out (costs: developer time, management involvement: granting permission). The other is a change in project plans, staffing, workflow and timelines (costs: large, management involvement: massive). I think it's a pretty safe bet to expect, for this reason alone, that the documentation quality of things like SwiftUI will improve over time. It seems pretty obvious they directed all their efforts to releasing SwiftUI within their iOS 13 release window, which likely meant the API only 'stabilized' very late in the process and it would be impossible to spend time and resources documenting it, at least not without postponing the release (not an option). Generally speaking, in my experience all of the 'established' Apple API's have pretty good documentation. SwiftUI seems rushed, and it would probably been better if they waited until iOS 14 and release it along with documentation. I'm not definding Apple here, but I think the article is overstating how bad their documentation is based on one brand-new API that probably wasn't fully cooked for release to begin with.
- mpweiher 7y ago
  As far as I can tell, this is individual developers reaching out, possibly at risk violating company policy. They do it anyway, and should be commended, but this isn't Apple per se.
scarface74 7y ago
Most developers who are making apps for iOS are working for companies that only care about money. There is no fanaticism about it. If developers optimized for working on platforms they liked, no one would write console games.
- greggman2 7y ago
  Um, hmmm, that is exactly the opposite of my experience writing console games. Console game dev is fun because you can push the machine to the limit and know every technique you use will work across all devices since they are all the same (or close enough). PC/Mobile dev is hell compared to that. I worked at a company that did mostly console, shipped one PC game, vowed never again as the support costs were several orders of magnitude higher than console.
  - scarface74 7y ago
    Game developers are some of the lowest paid, most highly exploited developers out their.
WrtCdEvrydy 7y ago
It's really funny to think about cyclical stuff and see how Blackberry used to treat their developers like shit (with stupid signing keys and stuff) and just look at Apple falling into the same trap.
- craydandy 7y ago
  And this reminds me of the documentation quality of Symbian around 2005-2007. I would highly recommend the author of the article the check it out, before lamenting Apple's documentation.
  - nullandvoid 7y ago
    I mean it's a discounted OS is it really a comparison? We're talking about one of the biggest platforms in the world here with unlimited money to throw at this problem there is no excuse
    - moron4hire 7y ago
      Seriously, Apple is one of the richest companies in the world (I don't remember if it's still The Richest or not). Similarly, Google's documentation is pretty bad, considering just how ludicrously rich they are. They could afford to hire entire teams whose only jobs were to write documentation and it would barely make a blip in their bottom lines. In contrast, I've always found Microsoft's documentation to be incredible. It can often be hard to find the right thing (though that has getting better, though that might be just my growing experience on how to find things), but they put real, actual effort into documentation. Also, Microsoft has a very strong "corporate style guide" for API design. Every MS API within their major silos is built exactly the same way as every other API. Once you've had some experience with them, it's easy to figure out the others. I find Android to be down-right schizophrenic in comparison. It's one of the many reasons I continue to focus on MS platforms for my work. It's been 20 years since they were the hostile "kill everything that moves" company that people lament.
      - mikestew 7y ago
gatherhunterer 7y ago
You criticize their rabid fans but aren’t you just as irrational? You have made claims that are so bizarre they cannot be supported by evidence. You are making emotional attacks that sound like someone talking about their high school bully. I don’t know how you convinced yourself that Apple is more interested in being aloof than in making changes that would help them make money but that belief is just as ridiculous as the belief that they are altruistic. “Apple” has become a trigger word for many people. It is strange that one would allow something they claim to dislike to have such a profound impact on them that it compromises their reasoning.
- chooseaname 7y ago
  Apple has a very long and very known history of ignoring problems until they can't. They'll get away with terrible/missing docs until they can't. > You are making emotional attacks... Am I?
- Dylan16807 7y ago
  > You have made claims that are so bizarre they cannot be supported by evidence. I, uh, example please? "Apple doesn't need to care" is in no way bizarre.
- computerex 7y ago
  https://www.engadget.com/2010/06/24/apple-responds-over-iphone-4-reception-issues-youre-holding-th https://www.engadget.com/2010/06/24/apple-responds-over-ipho... https://9to5mac.com/2019/02/11/italian-apple-homepage-to-add-iphone-battery-throttling-advisory/ https://9to5mac.com/2019/02/11/italian-apple-homepage-to-add... https://www.theverge.com/2017/12/28/16827248/apple-iphone-battery-replacement-price-slow-down-apology https://www.theverge.com/2017/12/28/16827248/apple-iphone-ba... https://www.theinquirer.net/inquirer/news/3032188/apple-faces-class-action-lawsuit-over-borked-macbook-keyboards https://www.theinquirer.net/inquirer/news/3032188/apple-face... These is just a very small subset of incidents with Apple where Apple failed to right their wrongs and was ultimately forced to do so by public and or legal pressure. Apple as a company is known for ignoring feedback altogether.
  - 7y ago

travisgriggs 7y ago

I work half and half pretty much maintaining the same app in both iOS and Android. Since the introduction of Swift, the Apple docs have become much terser (it's like Jony Ives slimness fettish got a hold of them). Even with that, they're better (by far) than what I find with the Android docs. The Android docs "explain" very little.

iainmerrick 7y ago
Android suffers a lot from quantity over quality. Classes are usually documented, but usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag. Edit to add: I also work on both platforms, and I’d say iOS (along with MacOS) is usually easier to work with because the design tends to be sane and the names are fairly descriptive; whereas Android has a lot of weird and questionable design decisions so it’s harder to guess how things really work. On the upside for Android, it’s often possible to just read the source code (at least for the core OS). I think the docs are about equally bad overall.
- andybak 7y ago
  > usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag. Ah - the "repeat the method names with spaces in it" style of documentation. This is merely an exaggerated form of a trap that the majority of documentation falls into to some degree - documenting the "what" but neglecting the "why" or "how". It tells you the bit you can easily work out by intuition, reading the source or using your IDE's features. And it leaves out the really important parts: "how should I use this method?" and "why would I need to?" Method based documentation also has problems explaining how API calls are used in concert. Understanding each method in isolation something leaves huge gaps in understanding how they are to be used together. And no - you can't plug the gaps with lazy video tutorials.
  - oefrha 7y ago
    > Ah - the "repeat the method names with spaces in it" style of documentation. That's usually a symptom of aggressive linters enforcing the rule that every single public method must be documented. Programmers then produce useless "documentation" to shut the linters up. Utter waste of disk space.

non-entity 7y ago

I haven't done a lot of work in Apple ecosystems, but what I have seen from their docs are admittedly pretty bad. Recently out of curiosity, I tried to figure out how macOS drivers are written and left more confused than I was before. Microsoft iirc, used to have their docs terribly organized (it was difficult for me to find what I wanted without a Google search) but they seem to have improved that nowadays

pmjordan 7y ago
Driver development docs on macOS largely haven't been updated in 10+ years. I started doing macOS kernel stuff when Snow Leopard was the latest release, and the only documentation I can think of since then has been sample code for Audio Server Plugins (for writing new-style audio drivers) and headerdocs explaining the transition from IOUSB* to IOUSBHost* APIs. Any additional information has been buried in a bunch of WWDC session videos, or you have to extract it from Apple by filing DTS incidents. On the other hand, Apple have decided a bunch of documentation was out of date, so they've simply made it harder to access by burying it in archive sections or taking it offline altogether, without providing replacements. Getting into driver development now is almost certainly a lot trickier than it was back then.
- saagarjha 7y ago
  I hope Apple credited you the DTS incidents back for something like that!
  - pmjordan 7y ago
    They have credited a bunch of DTS incidents back, but that normally only applies where they determine that they either: * can't help you * don't want to help you TBH, compared to the person-hours required to write up the DTS incident in the first place and keep the conversation going, test out their responses, etc., the cost of the incident itself is minimal. Let alone the cost of the times where I decide to go it alone and figure it out by trial & error or reverse engineering…

Amorymeltzer 7y ago

Last week's ATP[1] had a segment on this, in particular a discussion of https://nooverviewavailable.com/ https://nooverviewavailable.com/ which has an estimated breakdown of what percent of each framework has documentation. 1: https://atp.fm/episodes/349 https://atp.fm/episodes/349

czr 7y ago
timestamped link: https://overcast.fm/+R7DXB8Hbs/14:08 https://overcast.fm/+R7DXB8Hbs/14:08

macinjosh 7y ago

I am sure all the documentation this guy has ever written has been 100% perfect. /s Calling out other people's work as 'garbage' is pretty shameful. In my experience Apple's documentation is some of the best around. They have sample projects showing you how APIs work, good integration into their IDE, and lots of talks on video about their APIs given by the very engineers that built the thing. Not even to mention their written documentation. This blog post offers no evidence or specifics as to what makes it 'garbage'.

ebg13 7y ago
> Calling out other people's work as 'garbage' is pretty shameful Apple is not a people. Apple is a TRILLION dollar megacorp. They can afford more.
- macinjosh 7y ago
  Yeah... but you do know that Apple is comprised of actual real people like you and me though, right?
  - jk563 7y ago
    And the author acknowledges that those individuals are not the problem. > the problem is not individual engineers — who are not responsible for writing docs; that is the responsibility of dedicated coumentation teams. But that does not make it any less a failure of Apple’s engineering organization.
    - fireattack 7y ago
      I get author's point, but this sentence reads weird. If a team ("dedicated [documentation team]") is responsible for something, surely the individuals in such team are responsible too? Or the author is making a distinction between "engineers" and team members of documentation teams?
      - chriskrycho 7y ago

tempodox 7y ago

Apple's developer docs have been incomplete since the introduction of OS X. I don't expect it to get any better before hell freezes over. The article mentions that this makes it hard for newbies to learn. That's true but my guess is that by the time those chickens come home to roost, JavaScript will be called a systems programming language. Edit: Updated wording to article's title change.

iainmerrick 7y ago
I wouldn’t put it quite as strongly as that, but yes, the OS X docs have never been great. It’s a shame, because the classic MacOS docs were amazing, amongst the best technical docs of all time at their peak. (I had a shelf of Inside Mac books, and they were useful for years.)
pier25 7y ago
Trying to learn Cocoa dev in 2019 is very frustrating. Not only there are practically no updated resources available (books, courses, etc), but the Apple docs are really lackluster. At first I thought Catalyst was about empowering Cocoa devs to bring Mac apps into iOS, but now I see it's just the opposite. I imagine the number of macOS devs has been slowly shrinking over the years.

gigatexal 7y ago

According to Marco of overcast and the ATP podcast fame the docs pertaining to the audio subsystem is really lacking.

oflannabhra 7y ago

A couple years ago, maybe around Swift's debut, Apple began to mark all their sample code, projects, programming guides, technical notes, etc, as deprecated and unmaintained with a header on each page stating so, and putting it all in their "Documentation Archive" [0] They've had a new push to make sure that the remaining official documentation is available in either Swift or Objective-C, but I have yet to see any attempt at migrating some of their best documentation: CoreBluetooth Programming Guide, CoreImage Programming Guide, or CoreData Programming Guide [1]. These are hugely helpful documents that take a much higher level approach than just API documentation and get to the heart of the design of a framework, with helpful diagrams, etc. I understand that Apple has a huge body of work regarding documentation, and that it would be unfair for us to require them to never deprecate any of their documentation, but at this point, we basically have header files, documents automatically generated by header files, with several large swatch of that even being undocumented [2]. I do think that Apple made a huge effort with SwiftUI to provide meaningful, helpful documentation at the time of the announcement [3], and I don't want that to get lost in the discussion. Unfortunately the framework has iterated so quickly that much of it is out of date. However, when Xamarin [4] independently documents some of Apple's APIs better than Apple does... it is indeed time for a call to action. This is especially sad because Apple used to have some of the best documentation ever available. I basically learned how to program through using their documentation. [0] - https://developer.apple.com/library/archive/navigation/ https://developer.apple.com/library/archive/navigation/ [1] - https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/CoreData/index.html#//apple_ref/doc/uid/TP40001075 https://developer.apple.com/library/archive/documentation/Co... [2] - https://nooverviewavailable.com https://nooverviewavailable.com [3] - https://developer.apple.com/documentation/swiftui https://developer.apple.com/documentation/swiftui [4] - https://twitter.com/akashivskyy/status/1187790245804367873 https://twitter.com/akashivskyy/status/1187790245804367873

protomyth 7y ago
Along with this, they removed or not generated PDFs like they once had. This is really painful for folks that have problems with looking at a screen for an extended period. They don't even have downloadable documentation that can be read on an iPad. The lack of PDF is a real issue for me. The continued failing of example code is really painful.

boris 7y ago

Their diagnostics is pretty cool, though. How about this gem: ld: warning: ignoring file build2/libb.u.a, building for macOS-x86_64 but attempting to link with file built for unknown-unsupported file format Going to steal that "unknown-unsupported" term for sure.

deleted 7y ago

[deleted]

supernes 7y ago

Developer goodwill is not really that essential to a lifestyle accessories brand.

scarface74 7y ago
Right because 50% of the US mobile market only buys a phone because it’s an “accessory”.
- wetpaws 7y ago
  Not sure if it is a sarcasm or not.
  - scarface74 7y ago
    Of course it’s sarcasm. It’s just like people who sat that the iPhone is a “status symbol”. How can something be a status symbol when 50% of smart phone users have it in the US and that anyone on any of the four major carriers can buy one an interest free 24 month loan. Geeks can’t stand to face the fact that people who can afford to have a choice, overwhelmingly shy away from Android.
    - orangecat 7y ago
      How can something be a status symbol when 50% of smart phone users have it in the US It's more that Apple has gotten people to view anything other than the iPhone as low status, e.g. green bubbles.
      - scarface74 7y ago
        So Apple has brainwasheded people for 20 years? Geeks have been saying that Apple was a status symbol since the iPod. As far as iMessage, it couldn't possibly be that Google has had four or five failed attempts at a messaging platform?
      - askafriend 7y ago

Phillips126 7y ago

Docs are always something I evaluate before moving forward with a specific tool or language for a project. I have not done much work in the Apple ecosystem but it surprises me that a company of this size would have lackluster docs. It makes me wonder how many non-Apple developers give up on their idea for an app due to frustration and how that translates to lost profit for Apple given their 30% cut. I am not a huge Golang fan but recently I found myself using Go quite a bit and I really appreciate their docs which include a description of each function and an example. The example code is even editable with a "Run" button so you could test and understand the function much better before moving it to your own code. Here's an example if you are unfamiliar with Golang docs (click the "example" link for the editable code): https://golang.org/pkg/strings/#Compare https://golang.org/pkg/strings/#Compare

cyberferret 7y ago

Still? It has been a while since I have done any Apple platform specific native development, but I remember about 5 or 6 years ago writing an iOS and OS X app for communicating with an audio modelling device, and the documentation for CoreMIDI was woefully lacking. I couldn't believe that a part of the Apple operating systems that had been ingrained for years had so little documentation and examples at that time. I ended up finding out more from a lot of third party blogs and via forums. I haven't checked, but are things like the MIDI framework still badly documented in the Swift docs?

AlanYx 7y ago
>I haven't checked, but are things like the MIDI framework still badly documented in the Swift docs? Documentation for the entire audio stack has actually gotten quite a bit worse. Many references have been removed without new replacements being provided. In many cases, there are broken links in what little documentation remains. (For example, TN2274, which describes the USB audio stack is still around, but several of the outgoing links, for example the documentation for developing a USB audio plugin, are now broken, with the sample code deprecated and removed with no replacement.) New frameworks like AVAudioEngine simply don't document important limitations, particularly for OS X. The Core Audio mailing list used to be a good place to get help and answers in cases where the documentation is weak, but traffic has withered and no from Apple seems to reply to messages any more. There has been a total of only four messages on the mailing list this month. It's really a shame, because the audio stack is well-designed, but the documentation is so poor except for the basics that newcomers would have difficulty getting anything tricky off the ground.
- tonynguyen1 7y ago
  This is so true. Audio APis are poorly documented. I have only done my task by customizing examples :).
- WWLink 7y ago
  I wonder if the people who worked on it don't work there anymore.
- 7y ago

jrochkind1 7y ago

15+ years ago, Apple had some of the BEST documentation. But I agree it's fallen precipitously.

Ididntdothis 7y ago
I worked a little on the Mac in the 90s and then their documentation was really good. You could read it like a book. Actually Microsoft was really good back then too with the MSDN library CDs they shipped. Not it’s pretty bad and getting worse all the time with a lot of broken links and tons of auto generated content that doesn’t explain the big picture.

deleted 7y ago

[deleted]

balls187 7y ago

My issue with this is that the developer is comparing his experience with Apple's documentation over a few months, with his anecdotal experience over 4 years. Part of gaining experience with a platform is the ability to source answers to technical questions effectively, including how to use official documentation effectively.

chriskrycho 7y ago
I'm extremely comfortable reading documentation for a very wide variety of platforms, languages, etc. (The first software I ever wrote was Fortran via `gfortran`. Trial by fire!) It's not just me. This is just straight-up absent: https://nooverviewavailable.com/swiftui/ https://nooverviewavailable.com/swiftui/ As I noted in the post, I'm getting by anyway… but it's more work than it needs to be, and more work/worse state of docs than other ecosystems I've learned in similar amounts of time.
- balls187 7y ago
  My comment wasn't about your comfort level. It was about comparing your experience 4 months in, to your experience 4 years in, anecdotally.
  - chriskrycho 7y ago
    Erm, yes. Any possible comparison anyone could do of their own experiences would by definition be anecdotal. I also know exactly what my first 4 months in other ecosystems were like. Including picking up Fortran! That was rough! :)

no_wizard 7y ago

I actually agree whole heartedly with the intentions behind this article. I find Apples documentation to be incomplete and not nearly as detailed as I think it should be. I think that personally it’s not all that well organized either. My minimum standard for good documentation has and always been Python’s[0]. While no documentation is perfect, I think they mostly get it right by providing good explanations and examples consistently throughout the documentation. I also like how it’s spilt up between modules and the code examples are routinely updated. I have found very little issue with Python’s docs. While it could definitely use more examples and and deeper content around asyncio in some parts (mostly around transports and protocols) on the whole its very good, to me it’s what all organizations should strive for at a minimum. I also want to call put Mozilla’s Developer Network (MDN)[1] as stellar, I reference and use it all the time and have genuinely been happy with it. To be fair in assessments, I’ve also found links in Microsoft’s documentation that often link to things they have already marked as outdated or not going to be updated, or just don’t work like the GitHub links on this page: https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/controls/views?WT.mc_id=docs-dotnet-xamarin https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-... So I think a lot of documentation around the big platforms especially have a lot of work to do. This isn’t to say documentation is easy though. I sincerely hope that all this noise just means it becomes more of a priority. I know from experience that writing good documentation is hard and I don’t want this to come across like I’m faulting anyone in particular or organization in particular. I imagine with large and ever changing platforms it’s quite the challenge. I just wanted to point to some examples I believe get it right most of the time. [0]https://docs.python.org/3/ https://docs.python.org/3/ [1]https://developer.mozilla.org/en-US/ https://developer.mozilla.org/en-US/

not_a_cop75 7y ago
php, whether you like the language, or abhor it, has always had some of the most useful documentation, I've found.
- richardwhiuk 7y ago
  I disagree. See Example 5 in https://www.php.net/manual/en/security.database.sql-injection.php https://www.php.net/manual/en/security.database.sql-injectio... This is the recommended way to avoid SQL injection, using sprintf...

jmull 7y ago

The Swift language has excellent documentation. For SwiftUI, the WWDC presentations are essential, IMO, for the high-level stuff. There is basic reference documentation, but there's no way to put it all together without a high-level understanding. It follows the patterns of some other frameworks so depending on your experience you may be able to get by without the WWDC presentations, but I'd still watch them or at least read the transcripts. I think Swift Package Manager is meant as a community tool, and the love and care it needs to become excellent is not going to be coming from Apple, not without some kind of strategic change. Either the community will value it and figure out how to move it forward or it's not going to get much better. I could be wrong -- I'm trying to judge it's on-going strategic importance to Apple -- but I think the way it's going to improve is through community involvement. Anyway, I'm not sure what the point of this kind of rant is. Whining about Apple is an easy way to get useless internet karma points, but it's such a bad look for a developer. At least half the job is being the one who finally deals with things someone else probably should have already dealt with but didn't.

andybak 7y ago
> For SwiftUI, the WWDC presentations are essential, Are these videos, slides and transcripts? I do hope not because none of those things are documentation by any reasonable definition.
- jmull 7y ago
  They are. I definitely don't think it's an ideal form. The content itself is high-quality, but I'd much prefer a well-written document. I point it out because if you want to learn SwiftUI your best approach is probably to start with the presentations, whether you like that form or not. Many will naturally avoid that kind of content and I'm trying to communicate that in this case you really should use the presentations.
chriskrycho 7y ago
Noted the first two bits in the post. Did you read it? :) As far as SPM goes: they've got it built into Xcode at this point, and are doing WWDC sessions about it. At what point does it become "official" enough to warrant "This needs to be better" criticism? As far as "useless internet karma points": I couldn't care less. History has shown that when people make enough stink about this kind of thing, it sometimes—rarely, but sometimes—gets to the ears of people high enough in the management chain that it ends up shaking things loose at the mid-level spots where poor decisions around these things tend to get made. I don't work at Apple. I can't go fix most of this stuff. In my day job, I spend a lot of time on these kinds of concerns. In this context, though, the only thing I can do is shout a bit and hope it shakes things up a bit.

fortran77 7y ago

It's always been bad, too! Back in the OS9 days, the Apple documentation was "cumulative". You had to know every trick, every hidden bit and flag, back to day 1 in order to write a program. It's no better today. People who live isolated in the Mac universe have no idea how good Microsoft Visual Studio tools are, and how complete and thorough the documentation is, and how consistent the API is. You don't have to wade through a 30 years of legacy APIs to get anything done.

heisenbit 7y ago
Woz documented every line of his Apple ][ system monitor code and it was a joy to read.
- fortran77 7y ago
  Yes! I've been around since those days.

ChrisMarshallNY 7y ago

Some time ago, I was contacted by Apple to apply for a job. My code is insanely well-documented. I like to think that a lot of the inspiration for my code docs comes from Apple's open codebases. Their code is exceptionally well-documented. In any case, as is usual with all employers, these days, they completely ignored the focused, relevant links that I sent them to elements of my extensive portfolio of repos, and, instead, based the entire interview on a 50-line binary tree test in Swift. I'll make it clear that I'm NOT a fan of these. I am mediocre, at best, at them, as I don't come from a traditional CS background (I started as an EE). In any case, during the test, I did what I always do when I write code. I stopped to write a header document for the function. This was clearly not something the tester liked. Also, to add insult to injury, they dinged me for not writing a cascaded nil-coalescing operator. The code they wanted me to write was difficult to understand, and absolutely not one bit faster. What makes this even funnier, was that this was for an Objective-C job, and the links that I sent them (that they ignored), were to ObjC repos. After that, I just gave up on them. It kind of shows where a lot of this is coming from. Dynamically-generated documentation can be great (It's clear that the lions' share of Apple's developer documentation is dynamically-generated), but it requires a VERY disciplined coding approach. I suspect that they may be hiring less-disciplined engineers, these days.

jtchang 7y ago
What is a "cascaded nil-coalescing operator" ?
- omaranto 7y ago
  Something like a.?b.?c which is syntactic sugar for: a && a.b && a.b.c (with a short-circuiting &&.)
  - rimliu 7y ago
    This is just optionals chaining, not nil coalescing.
    - 7y ago

mlang23 7y ago

One Cook can ruin many meals.

butuzov 7y ago

This comment has nothing to do with apple, but about documentation in general. I was trying to get into Kubernetes world via kubeflow, a machine learning platform that works on top of the Kubernetes. Well, I have run into a bunch of the missing examples, outdated articles, and things that just don't work (all of that in official documentation). I decide to change this a bit and start working on a small tool [1] that can help check documentation (at least reduce deadlinks in the documentation, when someone moves git files or just original source of info dies). Since I start working on it, I meet only one project without issues, all others.. well, they all had issues. Maybe one day I post it on HN as a standalone link, but now here we go [1] [1] https://github.com/butuzov/deadlinks/tree/develop https://github.com/butuzov/deadlinks/tree/develop

coldcode 7y ago

I've spent most of my programming life doing Apple stuff (in between Java and C++ non Apple stuff too) and the only really good docs they ever had was the old paper Inside Macintosh in the 80's. Even when I worked at Apple at DTS in the mid 90's we had to hire someone to go around to every engineering dept and find out wtf they just shipped to provide developers something, anything, as documentation. That was back when Apple lost tons of money. Now the excuse can't be financial. Maybe they don't care enough?

edw 7y ago

Nowhere in the comments thus far has anyone pointed out that SwiftUI — the framework in TFA's crosshairs — is in beta. I've written a relatively large amount of SwiftUI code and I get the impression that the design is still in flux. There are corner cases (as well as much more mainstream one) that haven't been fully thought through. Beta 5 of Xcode 11 brought non-trivial changes to the API and I expect those to continue. "It's not finished until it's documented" is a fine sentiment, but I don't think Apple has remotely claimed that SwiftUI is finished.

oflannabhra 7y ago
As I noted in another comment, the documentation for SwiftUI is actually pretty good, especially if you take into account how quickly the framework has changed. It includes some rich, progressive tutorials. [0] The author states that they are planning to write an app from scratch with SwiftUI. I think most iOS developers would hesitate to build an entire app on a beta framework. [0] - https://developer.apple.com/tutorials/swiftui/tutorials https://developer.apple.com/tutorials/swiftui/tutorials
- mistahenry 7y ago
  They would also hesitate to build an app that only works in iOS 13+ when iOS 13 is the current iOS
- chriskrycho 7y ago
  These tutorials are great (when they're working! That's been a bit spotty)—genuinely great. But they don't make up for everything that isn't present. Take a step off that beaten path and you're in for a world of pain today.
- varenc 7y ago
  The SwiftUI tutorials also have quiz questions at the bottom to test your understanding of the tutorial. Never seen that before but seems like a great idea https://developer.apple.com/tutorials/swiftui/creating-and-combining-views#check-your-understanding https://developer.apple.com/tutorials/swiftui/creating-and-c...

meh206 7y ago

They're too big to care.

mmusson 7y ago

When I first learned iOS ten years ago I thought the documentation was outstanding. It had good API level documentation as well as a large number of guides that showed the right way to use the API to implement particular features. I recently returned to the platform and my experience is very much like the parents. The documentation appears to be almost completely missing. The built-in documentation does not appear to include any guides at all. The API documentation is largely the kind where the description is a more verbose form of the method name, and sometimes when Objective-C is selected the documentation is showing the Swift version.

mmusson 7y ago
I have discovered that the previous documentation is still available in a “documentation archive” complete with banner warnings about how it is out of date and unsupported. It is almost impossible to find topics except by using google search. Newer functionality is missing and some of it is no longer accurate, but it is better than nothing.
- topherPedersen 7y ago
  I've had to resort to referencing the documentation archive before as well. While the new docs are certainly prettier, the old docs were much more substantive.

gnachman 7y ago

The comments in header files are often the only (or only useful) documentation. So don’t give up before looking there. Sometimes they wait a few years to write docs. For example, NSWindowAccessoryViewController went undocumented for three or four years. Which was fine because it was too buggy for me to use anyway. The docs are enough to get you started but it’s only brutal experience that teaches you how to use things. In practice you spend a lot of time working around bugs and design flaws. Those will never be documented, of course.

WWLink 7y ago
Yeah, I developed software for a platform that isn't documented anywhere at all on the internet, and the documentation it comes with is sketchy. Discovering a new widget and spending time messing around with it was the norm.

Shank 7y ago

Maybe I'm the only one, but when I start looking into a project, I start at the API docs and work from there. I really need to know if key features I want are viable on the platform or not. If I want to use an accessibility API to, in a supported way, read all of the items in every menu in the menu bar, how do I do that? Is it supported? Is there a set of best practices I should follow? The problem with not documenting things is that developers like me are turned off before we start. I don't want to bend the platform so far that it breaks. I want the limits. I'm tired of reading stories about apps being pulled for using private APIs, or breaking in future versions because they're removed. I want to do things in a supported way so I can make everyone happy. Right now, I can't even see the boundaries of what's possible, because nothing is documented. I don't even want to try to write for Apple platforms, because it's entirely inscrutable and unpredictable.

bob1029 7y ago
You are not the only one. My most recent experience with Apple's documentation (regarding some iOS 13 API concern), left me with a sense of impending doom and hopelessness. After about 5 minutes I gave up and went back to playing the google/stackoverflow search game. I have become very addicted to the quality of Microsoft's documentation for things like .Net Core & C#, and have found it virtually impossible to tolerate reading documentation from any other vendor at this point. A completely arbitrary but hopefully obvious side-by-side comparison: Exhibit A: https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.distinct?view=netcore-3.0 https://docs.microsoft.com/en-us/dotnet/api/system.linq.enum... Exhibit B: https://developer.apple.com/documentation/coreimage/cicolor/1438084-init https://developer.apple.com/documentation/coreimage/cicolor/...
- lilyball 7y ago
  It's unclear to me what you think Exhibit B is demonstrating. That's the documentation for CIColor.init(red:green:blue:alpha:), and it's documented. It creates a CIColor with the specified red/green/blue/alpha components. This is literally just a model object.
  - 7y ago

perfectstorm 7y ago

So much this. The other day i was trying to look up documentation for Swift’s KVO and i couldn’t find one. I know there’s a KVO API that accepts a closure but i just couldn’t find where it is. smh. Apple used to link sample code with pretty much all the big APIs but they no longer do that. If you want to see how an API is used or see the best practices you’re better off checking stackoverflow.

Austin_Conlon 7y ago
When I learned that you could filter by sample code in the bottom left search box of Xcode's documentation window, it made sample code a lot more discoverable for me. Of course that's far from ideal though, and they should be linking to sample code more in the documentation.
saagarjha 7y ago
You're looking for NSObject.observe(_:options:changeHandler:), which doesn't seem to have a dedicated documentation page that I can find but it's mentioned here: https://developer.apple.com/documentation/swift/cocoa_design_patterns/using_key-value_observing_in_swift https://developer.apple.com/documentation/swift/cocoa_design...

CalChris 7y ago

For a company with a capitalization of $1.123T, yeah, Apple is pretty cheap on the developer documentation.

rubyn00bie 7y ago

It's funny to read this and have it compared to Ember's docs, especially since I've been using Chris's site a fair bit over the past few months... I only bring this up for posterity, but Ember's documentation is terrible, and what is even worse is the Typescript documentation is almost unusable its so outdated. Chris's site is the only place you can go to find anything and it's incredibly difficult to make sense of or is already completely outdated... There are constant gotchas and missing documentation or things that are flat out wrong... I can understand complaining some about Swift's docs (though I've never had that problem), but comparing them to Ember's seems like an awfully bad take. P.S. I love Ember, learning it has just been nightmarish at points for almost no reason.

chriskrycho 7y ago
1. You should file issues against Ember's docs! We have different experiences of it for sure. Even just as experience reports, I know the folks who work on it would love that. 2. The Ember TS stuff is in need of an update—desperately—as are my (several-years-old-now!) blog posts. Unfortunately (unlike Apple) none of those of us who work on it get paid to do so at the moment – at all, including docs. I'd love it if you opened issues against the ember-cli-typescript repo about specific issues/confusions you've had.
- rubyn00bie 7y ago
  1. Totally, I have, will do more, and would like to... One big difficulty I've had, because I want to fix things (like docs), is because everything post 3.12 is geared towards Octane and those docs are all quite a bit different than everything before it... (and I'm on 3.12) it makes finding the code to change, text, blob pretty difficult (IMHO) since master is mostly Octane. 2. I know you aren't paid and you're a saint for all you've contributed! You've helped me an insane amount, and I want to say "thank you," for it. I wasn't trying to give you too much shit, I just thought it was a little funny... Ember's docs are in disarray for a new language and design patterns, and so are Swifts! ;) I probably should've used a softer word than "awful," my apologies. 2.1 I'll see you in your issue tracker later today :) Thanks for being friendly! I super appreciate it, and for letting me know about it being cool opening those kinds of issues. A LOT of Github repos are hostile to _any_ questions at all (i.e. "go to stackoverflow or take a hike"); so, I tend to not make issues and only PRs.

lasermike026 7y ago

If there is a problem with Apple documentation issue a bug report. I'm not from apple but I worked in their ecosystem for some time. When you experience real problems your manager or CTO might have to get in touch with a managing director. If you go to WWDC make sure you complain directly to the guys wearing the checkered shirts. They are the ones in change. The cool thing about WWDC is that you can communicate directly with Apple developers. They will even look at your code to help.

saagarjha 7y ago
> When you experience real problems your manager or CTO might have to get in touch with a managing director. If you can… > If you go to WWDC Again, if you can…

russellbeattie 7y ago

Every once in a while I think to myself, "I have a problem with OSX, I think I'll try to automate it with JavaScript for Automation (JXA)..." You know the rest. The astounding lack of documentation is almost amusing. It becomes an adventure of trying to convert old AppleScript examples into JS, spelunking into GitHub and StackOverflow and general trial and error until I get something to work. All this said, I'd rather have functionality without documentation, than the extreme of not launching an API without proper docs. The solution of course - though Apple would never do this as it's not in their DNA - is to let devs add to their docs like PHP does. I'd be happy to add back a few examples to their site once I figured things out if that option was available to me, but right now there's really no central place for this besides random forums or starting my own repo.

saagarjha 7y ago
Nobody seems to use JXA, unlike some of the technologies that are heavily used but just as undocumented :(
- russellbeattie 7y ago
  I don't disagree, but you might be confusing the chicken and egg. Maybe if Apple actually documented JXA... (it's actually quite useful).
  - saagarjha 7y ago
    I know it is, but I have little hope that it ever will. Everything I've heard points towards the OSA team not doing so hot these days.

strictfp 7y ago

Apple payments APIs are the worst APIs I've ever worked with. They're inconsistent, badly documented, have unannounced breaking changes and contain so many gotchas it isn't funny. For example, some of the most relevant data is attached to the response but isn't officially supported and may or may not be correct. It's not exactly fun to code up payment integrations, and so I was kind of hoping to get it over and done with. But with Apples payment APIs, we needed months of production data to figure out how to use them without shooting ourselves in the foot. Using the API felt like interfacing with some badly configured eventually consistent MongoDB cluster that a bunch of juniors stuffed full of receipts, using the entirely wrong data model.

kalleboo 7y ago
And what's worse is the "sandbox" for testing behaves completely different from the real store, and has random undocumented downtime and bugs that you only find out about from other people reporting it on the developer forums. And creating, logging in to, and keeping sandbox accounts from contaminating your real devices is also a PITA.

hugey010 7y ago

I've developed native iOS and Android apps professionally since 2012 and I always found their docs to be a mix of amazing - https://developer.apple.com/design/human-interface-guidelines/ https://developer.apple.com/design/human-interface-guideline..., and fairly useless - https://developer.apple.com/documentation/vision https://developer.apple.com/documentation/vision. All example code I've seen provided by Apple looks like a Fisher-Price® My First UIViewController toy. It is my belief that the Apple iOS docs are just another barrier to developer entry; similar to their $100 yearly license, expensive hardware combined with their WYSINWYG simulator, and woeful iTunesConnect experience. These barriers to entry, including the poor documentation, definitely have some interesting affects on the ecosystem. I've seen examples of all of these in the real world. * Experienced iOS devs have a shared trial by fire experience. * iOS salaries are slightly higher on average compared to Android. * Skilled iOS devs tend to be excellent developers in general. * Average iOS devs can be more arrogant and less likely, or less capable, of helping out in other languages and projects. (Apple framework specialist pigeonhole principle) * There is almost zero culture or standards regarding application architecture or documenting iOS apps. * Underlying "older" concepts like memory management have been masked, forgotten, and / or ignored.

oh_hello 7y ago

Apple's developer guides were amazing. I was able to read through them and become a proficient iOS developer. They are now archived and not updated. Even with experience on the platform, I now often find it hard to navigate the docs and learn major new frameworks. It is a real shame.

thfc06 7y ago

This is exactly what I've been dealing with for the last month, as I attempt to completely re-write an Electron app in Swift. The part about scavenging through WWDC transcripts particularly resonated with me. Coming from JS ecosystem, I was also shocked at how few google results (even stack overflow) would come up for issues I was running into.

rayascott 7y ago
What annoys me about Apple, is that clearly their time is valuable to them, but us paying Developer Program members are forced to waste days worth of business hours hunting through their appallingly maintained "documentation". And that really pisses me off.

microtherion 7y ago

OPs criticism is definitely justified, and it makes me sad. In my opinion, the peak of Apple documentation was the new, refactored edition of "Inside Macintosh" in the 1990s: https://en.wikipedia.org/wiki/Inside_Macintosh https://en.wikipedia.org/wiki/Inside_Macintosh Not only is there not enough information, but the documentation team goes out of their way to reorganize what documentation exists every couple of years, so outside links into the docs constantly go stale.

carapace 7y ago

Funny meme on the wall at Google: Picture of Governor Tarkin on the Death Star captioned, "Documentation? At our moment of triumph?" Still makes me laugh.

ngcc_hk 7y ago

Reading hundred comments and the op is about the lack of documentation. Swift is a good language to learn but api no. The discussion might explain it. But should there be one to address that issue as an ecosystem. For example ask Apple to do something and let them sort that out using their employee. Or some web site (I use one particular to help me). Swift is a language like lisp or clojure. You may look at its architecture etc to see whether it is built in issue (lisp is easy but its library is not, say). Or it is really just a hiring issue. Or may I just ask how to address the original question if it is just language lack of good doc.

novok 7y ago

Apple under invests in developer tooling relative to what it does. The dev tooling teams are surprisingly small and the internal dev experience at apple for their own employees is pretty bad compared to other large tech companies. My guess partly is because of the siloed nature of the company, and they don't sell dev tooling for "money".

jariel 7y ago

Absolutely true: if it's not well documented, it's not a product, it's borderline useless. Apple is just one of many 'big companies' that strangely under-document so many products, frankly it's bizarre. If you don't have good docs, tutorials and snippets, it's not 'done'. iOS, Qt, many frameworks: spending days, sometimes literally weeks writing 'tiny experiment code' to navigate the ambiguities or missing parts of docs, it feels totally unacceptable to have to do this. This is a hugely important statement the author is making.

OliverJones 7y ago

Agreed this is a big problem. Sometimes sitting through a WDC tutorial video can unearth answers. But, really? You know, they could call Tim O'Reilly and commission a bunch of excellent books. They have the money and Tim has the writers.

TheKarateKid 7y ago

I’m surprised no one has complained about the lack of documentation for Safari, especially on iOS where special behavior is done for mobile. The best I could find from Apple was several years old, and clearly not up to date as the behavior no longer functioned as documented.

pier25 7y ago
Indeed. Stuff like the strange behaviour of <iframe> on iOS is not documented anywhere but StackOverflow or WebKit's bugzilla. For those that don't know, you can't set the height and width of an <iframe> on iOS. Something which has been possible in all browsers since the tag exists.
saagarjha 7y ago
There is this: https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/Introduction/Introduction.html#//apple_ref/doc/uid/TP40002051-CH1-SW1 https://developer.apple.com/library/archive/documentation/Ap.... Not sure if this has what you'd need.
- TheKarateKid 7y ago
  Came across that, but it's terribly outdated. Bottom of the page even says last updated in 2016.

danielinoa 7y ago

Funny thing is Microsoft has much better documentation on Apple's very own frameworks. Simply compare their documentation on this arbitrary type (CIAffineClamp): Microsoft's Documentation: - https://docs.microsoft.com/en-us/dotnet/api/coreimage.ciaffineclamp?view=xamarin-ios-sdk-12 https://docs.microsoft.com/en-us/dotnet/api/coreimage.ciaffi... - https://docs.microsoft.com/en-us/dotnet/api/coreimage.ciaffineclamp.-ctor?view=xamarin-ios-sdk-12 https://docs.microsoft.com/en-us/dotnet/api/coreimage.ciaffi... Apple's Documentation: - https://developer.apple.com/library/archive/documentation/GraphicsImaging/Reference/CoreImageFilterReference/index.html#//apple_ref/doc/filter/ci/CIAffineClamp https://developer.apple.com/library/archive/documentation/Gr...

devin 7y ago

As someone who has only recently gotten into producing an app for iOS, I was immediately struck by the lack and quality of the docs. It’s nice to hear that I’m not alone. The lack of documentation led me to feeling like I was just somehow personally missing something. I’ve been at this for awhile and the apple docs left me feeling like a junior programmer all over again. I wanted to first blame myself, but it’s become clearer to me that Apple just doesn’t care about supporting devs. That’s the theme for years now and it only seems to be getting worse. Bummer.

rasta78 7y ago

It's unclear to me how this post made to the top when it references SwiftUI - a framework which is still in beta and shouldn't even be brought into discussion. On the other hand, UIKit is documented about ~90% which is an insane amount and this is what most of the iOS devs are using on a day-to-day basis.

catchmeifyoucan 7y ago

Might just be me - but I'm attracted to well formatted docs. It's not a dealbreaker but I do appreciate when the fonts, spacing and code snippets are well thought out

specialist 7y ago

Sample code (showing usages) and tests are also part of the documentation.

smacktoward 7y ago

Apple's just doing with documentation what they do with everything else: making it thinner at all costs.