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.
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:
> 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.
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.
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.
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.
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).
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.
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.
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:
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.
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
IMHO that's usually a good sign --- that the API you're using is not ever going to change again. MS values stability and backwards compatibility far more than others (and in the past, that was even better) so "not going to be updated" means "this has become mature and stable, don't worry about unexpected changes."
For things like those broken links on docs.microsoft.com, you can file an issue (using the on page feedback tool, which generates github issues), or even send a pull request to the docs: https://github.com/MicrosoftDocs/xamarin-docs
Funny thing is Microsoft has much better documentation on Apple's very own frameworks. Simply compare their documentation on this arbitrary type (CIAffineClamp):
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]
Last week's ATP[1] had a segment on this, in particular a discussion of https://nooverviewavailable.com/ which has an estimated breakdown of what percent of each framework has documentation.
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.
Edit: this first paragraph is wrong, see child comment. Leaving for posterity. The second paragraph I stand by.
SwiftUI is not in beta. It may be beta-quality, but they shipped it and encouraged devs to use it. Yes, it has undergone significant breaking changes since WWDC (and that's to be expected), but it's not described as beta anywhere in their docs about it. (See https://developer.apple.com/xcode/swiftui/ and https://developer.apple.com/documentation/swiftui/ for what the docs actually say!) My point is that if they want to say "This is ready for you to adopt" they need to back that up by documenting it. Even at an early stage.
Facebook manages this for React, even for stuff that is in "experimental" mode! It's possible! It just has to be prioritized. (I'm no FB partisan and don't use React; the point is independent of those.)
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.
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.
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.
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?
>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.
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.
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
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.
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.
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.
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.
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?
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.
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.
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.
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
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.
[+] [-] Shank|6 years ago|reply
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|6 years ago|reply
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.enum...
Exhibit B:
https://developer.apple.com/documentation/coreimage/cicolor/...
[+] [-] tompetry|6 years ago|reply
[+] [-] chooseaname|6 years ago|reply
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.
[+] [-] WrtCdEvrydy|6 years ago|reply
[+] [-] scarface74|6 years ago|reply
[+] [-] sillysaurusx|6 years ago|reply
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
(I'm not an Apple fanboy, just a dev.)
[+] [-] gatherhunterer|6 years ago|reply
[deleted]
[+] [-] travisgriggs|6 years ago|reply
[+] [-] iainmerrick|6 years ago|reply
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.
[+] [-] mmusson|6 years ago|reply
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|6 years ago|reply
[+] [-] no_wizard|6 years ago|reply
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-...
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/
[1]https://developer.mozilla.org/en-US/
[+] [-] userbinator|6 years ago|reply
IMHO that's usually a good sign --- that the API you're using is not ever going to change again. MS values stability and backwards compatibility far more than others (and in the past, that was even better) so "not going to be updated" means "this has become mature and stable, don't worry about unexpected changes."
[+] [-] adonese|6 years ago|reply
GO docs are quite very neat and helpful though.
[1]: https://docs.python.org/3/library/argparse.html
[+] [-] jsmith45|6 years ago|reply
[+] [-] not_a_cop75|6 years ago|reply
[+] [-] carapace|6 years ago|reply
PHP's docs are the minimum standard, IMO.
[+] [-] danielinoa|6 years ago|reply
Microsoft's Documentation: - https://docs.microsoft.com/en-us/dotnet/api/coreimage.ciaffi... - https://docs.microsoft.com/en-us/dotnet/api/coreimage.ciaffi...
Apple's Documentation: - https://developer.apple.com/library/archive/documentation/Gr...
[+] [-] butuzov|6 years ago|reply
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
[+] [-] Amorymeltzer|6 years ago|reply
1: https://atp.fm/episodes/349
[+] [-] czr|6 years ago|reply
[+] [-] edw|6 years ago|reply
"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.
[+] [-] chriskrycho|6 years ago|reply
SwiftUI is not in beta. It may be beta-quality, but they shipped it and encouraged devs to use it. Yes, it has undergone significant breaking changes since WWDC (and that's to be expected), but it's not described as beta anywhere in their docs about it. (See https://developer.apple.com/xcode/swiftui/ and https://developer.apple.com/documentation/swiftui/ for what the docs actually say!) My point is that if they want to say "This is ready for you to adopt" they need to back that up by documenting it. Even at an early stage.
Facebook manages this for React, even for stuff that is in "experimental" mode! It's possible! It just has to be prioritized. (I'm no FB partisan and don't use React; the point is independent of those.)
[+] [-] oflannabhra|6 years ago|reply
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
[+] [-] rubyn00bie|6 years ago|reply
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|6 years ago|reply
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.
[+] [-] cyberferret|6 years ago|reply
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|6 years ago|reply
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.
[+] [-] strictfp|6 years ago|reply
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.
[+] [-] Phillips126|6 years ago|reply
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
[+] [-] thfc06|6 years ago|reply
[+] [-] rayascott|6 years ago|reply
[+] [-] gnachman|6 years ago|reply
[+] [-] WWLink|6 years ago|reply
[+] [-] coldcode|6 years ago|reply
[+] [-] fortran77|6 years ago|reply
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.
[+] [-] hugey010|6 years ago|reply
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.
[+] [-] oflannabhra|6 years ago|reply
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/
[1] - https://developer.apple.com/library/archive/documentation/Co...
[2] - https://nooverviewavailable.com
[3] - https://developer.apple.com/documentation/swiftui
[4] - https://twitter.com/akashivskyy/status/1187790245804367873
[+] [-] microtherion|6 years ago|reply
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.