I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!”
Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me.
So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medium posts because something from before WWDC 2020 might no longer be useful. Or maybe it is. How do you know if the feature changed significantly in the more recent release? I don’t know, but I can tell you where you won’t find out: the official docs.
I will say that the WWDC sessions are well presented, and are a good place to start. But you can't use a video for quick reference, and you might be missing context from knowing how it worked the previous year to understand what the new enhancements are. Expect to dig into 2019 videos too. SwiftUI being new at least has the benefit that its sessions can't be any more outdated than that (yet). At most you're reconciling two years.
The Landmarks tutorial is also very well done as a starting point. But a tutorial isn't a substitute for documentation.
I hate that WWDC videos have essentially replaced docs. Videos have to be shallow, and code on slides has to be short. This medium is fine to sell an idea, and to give a high-level overview of how it works, but there's no way to include as much information as written documentation would.
Here's a TED talk on Thorium reactors. Why aren't you running them yet?
For all the hate it gets, I think the way PHP does their documentation is ideal. Easy to search for what you need, it recommends other, similar classes/functions, gives a good description of the inputs and what something is expected to return. Then, in addition to that, there's the user-supplied examples and commentary to help further clarify things. I really like the model they went with.
I concur and add that PHP has actually evolved quite nicely, and it's horribleness is merely an outdated meme. Java is still playing catchup to the stuff PHP has added in recent years.
Just because it was shit 15 years ago doesn't mean it's still shit now.
IMHO there are still some edges that drive you mad until you remember them but the documentation is really good and every release is full of improvements. Also many available frameworks and tools in PHP world are outstanding. For me PHP provides a serious Rapid to Market Edge.
The inconsistencies are either fully removed (many in 7.x, more in 8.x), deprecated, or at least very well documented these days (e.g. with top level documentation warnings about any potential pitfalls).
That's certainly true for the standard library and the documentation on the language itself. However for the internals, this wasn't always the case and it looked more like this:
I also really dislike that WWDC videos are now the de-facto documentation. It must be a lot of work to put them together – I wish they'd just write a doc instead. Would be way faster to read, search, etc. and could probably go into much greater depth.
Same; there's so much important information in the WWDC videos, and part of me wanted to watch them all when I was still doing iOS development. But I can't watch videos, I don't have the attention span, and sitting to watch / listen just makes me go to sleep.
It's a me thing, not down to the presenters or anything. But all that I ask is documentation and / or blog posts.
I hope that anyone that is making a presentation also writes down the contents as a blog post and/or documentation. Please. For examples, Go's blog is pretty good (although there too one is often pointed at a presentation or slide deck for certain subjects)
Global search for all WWDC transcripts also isn't good on the website, you now how to reveal the transcript for each individual result after you search. In the Apple Developer app (where I would've expected a better user experience) it's not even possible.
On top of that they often contain pre-first-beta information so they are rapidly obsolete. Although the gist of the information is useful, the signatures and examples are not.
I don't really consider most WWDC videos documentation. They're usually just marketing videos which show off the new features. Even the more in depth videos are rarely more than a shallow introduction.
There's also a lot of useful information that has only ever appeared in Twitter conversations between Apple developers but I wouldn't call that documentation either.
I've run into this more often than I can count with Java based things. "Just look at the Javadocs!" You...you mean the auto-generated API descriptors that have exactly zero usage information on them, and expect me to figure out how to piece things together just by type signature? That...that isn't how documentation works.
That I could probably look at the source and figure things out.
No, what kills me is
public Session getSession(Foo, Bar, Baz)
where Foo, Bar, and Baz are themselves interfaces, and I have no idea what implementing class I need, so I go searching, and after an hour of pain piece together that I need to instantiate a NotAtAllAFooButNeverthelessImplementsFoo, then pass that into the BuildingFactory class' static factory method to get an instance of Bar, and then I can just pass in a null for Baz, and it -seems- to work.
Take 30 seconds to read through that and the linked pages (that's all the time it will take) and see if you could figure out how to use a PreviewDevice to make your preview show a particular device.
It will tell you all the ways to initialize a PreviewDevice struct (from many different varieties of String), but you'll have no fucking idea what to do with that object.
And here's an actual code sample, via Paul Hudson:
struct ContentView_Previews: PreviewProvider {
static var previews: some View {
Group {
ContentView()
.previewDevice(PreviewDevice(rawValue: "iPhone SE"))
.previewDisplayName("iPhone SE")
ContentView()
.previewDevice(PreviewDevice(rawValue: "iPhone XS Max"))
.previewDisplayName("iPhone XS Max")
}
}
}
It turns out what you need to do is pass the PreviewDevice instance into a previewDevice modifier that you've applied to your view inside a struct adhering to the PreviewProvider protocol. I don't think this docs page even mentions that the previewDevice modifier exists, let alone how to put any of these pieces together to configure and display a preview.
You can find how to do this in tutorials elsewhere on Apple's site. But you can't find it in their documentation for Previews, because it's a bunch of automatically generated pages of function signatures with no explanation.
an example for `PreviewProvider#previews` uses `.previewDevice("iPhone X")`, and i'm guessing that that string gets turned into a `PreviewDevice` via one of those `fromBlahLiteral` methods it implements? my guess is that `PreviewDevice` is some kind of opaque handle thingy (which is why it has no visible members/methods) but that... really should be documented
Good find! For some reason buried two levels deep from the Previews page. I believe you're right that it's silently building a PreviewDevice from the string. You can make the PreviewDevice explicit (as shown in the Hacking with Swift code sample), but nice tidbit that you don't have to.
We tried to buy some mechanical equipment which can be steered by a computer API. I asked for the doc beforehand. Got something like your example (10 pages of C header). I asked any better docs? Answer:'a real programmer would know how to use this' - well somehow they didnt manage to sell the device to us. Later they managed to email the comprehensive docs (which existed!), but we alread spent a much larger amount (without regrets) to the competition.
rustdoc has the ability to embed usage examples in the doc comments, and automatically test them. also module-level documentation is doable via doc comments in the module main file. rust doesn't force you to write good documentation, but the tools are all there and I often see great documentation for rust crates that was generated with cargo doc. For example the Rocket docs are full of code examples on both the module and function level: https://api.rocket.rs
I think there's something to be said for javadoc, cargo doc, etc encouraging documentation to hew closely to the structure of the code as opposed to a free-form documentation system that can include multiple pages about tasks, getting started, etc. But the vast majority of projects don't bother to set that up, and the javadoc approach makes it very low friction to add docs to existing code that probably already has comments explaining how to use it.
That’s the barebones minimum, because in those contexts the examples are going to be relatively trivial. Often I find them to be no more helpful than the signature doc itself.
Even trivial examples that actually compile are better than none. because rust uses real code and markdown reading code and docs is the same thing in many cases, no need to even render to html, absolutely minimal markup noise.
I love rust docs. Speaking from many years of using mostly poorly maintained javadocs and well maintained man pages.
I wholeheartedly agree. The documentation is sparse and 3rd party tutorials have to be recent. That's why I still hold back for adoption.
Paul Hudson has really good material but I wish I could just leave a tab open with the official documentation and be prepared for most challenges. OTOH, things like Core Audio where never really well documented.
For learning Swift I recommend https://www.swiftforgood.com, no affiliation (also there Paul Hudson wrote the chapter about SwiftUI).
> So instead you end up on 3rd party tutorials...How do you know if the feature changed significantly in the more recent release? I don’t know, but I can tell you where you won’t find out: the official docs.
Get ready for documentation subscriptions. I wish I were joking.
They actually have a department to write the documentation. The problem is that it’s a separate department from the people who design the libraries themselves, which means instead of having high quality documentation throughout, you only get the documentation that the doc team had time to write. It’s why most of the APIs are minimal at best in terms of documents.
While the level of documentation that exists is usually pretty good, the sad fact is that most documentation doesn’t exist, and it’s entirely due to the fact that they are handled by developers/documentors separately. If you had developers documenting in-situ in the code, instead of WWDC slides, then it would be a lot better.
I don't think this truism actually holds weight. Some engineers don't want to write documentation, sure. Maybe even most don't - but some actually do enjoy the process of writing good documentation, and they find satisfaction in creating knowledge artifacts that make their code easy to understand and use. It's not enough to just find these engineers, however - they need organizational support so that they have the right tools to create and share good documentation, and are appropriately encouraged to do so.
A trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.
For Microsoft it depends on when the docs were written.
The MS docs from the late '90s through about 2015 were stellar. For example, look at the Windows Sockets docs[1], which came out of that era. Here you see information architects working at the height of their power: Content is broken up into conceptual ("About Winsock"), task-based ("Using Winsock"), and reference ("Winsock Reference") topics. They were doing this kind of structured documentation before DITA was a thing. It's a pain in the ass to produce content this way, but the results are wonderful.
Then came .NET Core: a fast-moving, community-driven effort, where the philosophy seems to be to get it working and then scribble down some docs later. The result tends to be a huge wall of text with conceptual and sample topics jammed together ([2]), and you're lucky if the API reference gives you anything beyond parameter names.
Azure docs suffer from a different problem. It seems they've tried to apply some kind of rough information architecture, but the quality isn't great. I've looked at the GitHub history of some of the shoddier topics, and they're often written by junior Product Managers who are fresh out of college. I encounter a lot of imprecise, colloquial English describing out-of-date screenshots.
I don't mean to belittle the people who work on .NET Core and Azure. There's a ton of content that needs to be written for these products, and it's a thankless task for the devs & PMs who do the heavy lifting now. I'd really like to see some dedicated technical writers come in and bring the quality back up to their old standards.
I use C# daily and most of the time the doc is fine. I agree that sometimes dotnet core docs are a bit messy and frustrating, but still quite good and useful.
For all the crap that Apple, Java and other open-source people have piled on Microsoft over the years, their developer documentation has always been very good. Yes, there are rough-edges.
Back in the day, when Sun was still in-charge of Java, I had my 1-person consulting company partner with Sun and become an official "Certified Java" organization... Great, I thought - now I can get some better documentation...
Sure, Sun replied - but first you have to buy a $30,000 server... Thankfully, .NET hit public beta about then and I have never looked back.
I wouldn't say it's always been very good. How well do you remember MSDN? In the mid-2000s, Microsoft documentation lived on three or four separate sites, and I don't remember the names of all of them. The two that spring immediately to mind are MSDN and TechNet. MSDN had the infuriating issue of broken links. You'd be deep-diving on an issue, find a link to an article that looked like it might perfectly address your question, and... 404.
It got so bad that a VP ended up making a pronouncement, declaring a war on broken links. He announced a multi-year plan to reduce and eventually fix all the broken links on MSDN. This was the vacuum that was partially responsible for the birth of Stack Overflow.
> It got so bad that a VP ended up making a pronouncement, declaring a war on broken links.
Probably Scott Guthrie initiated that. As some nobody I once emailed him directly because I'd discovered a bug in some framework thing with a reproducible example. He actually replied and cc'd in the relevant people at MS and after a short while there was a workaround and a fix and a KB article or something (it's so long ago I barely remember). Impressed? absolutely. MS still have some pretty good and accessible folks, and I'm a huge fan of Scott Hanselman who's a great brand ambassador for DevDiv (and not beyond a few self-deprecating MS jokes about the company's past).
They also suffered the same problem mentioned in this post.
Documentation pages that showed a method's signature with no explanation of the function or example usage. So many times I'd look something up only to find the method name parroted as a full sentence; and those method names were often obscure to the point of meaninglessness.
In late-90s to mid-00, if you did any serious Win32 or .NET development, you had the MSDN Library installed locally - it had its own help browser, with integrated search and index. The latter was especially useful, since it contained all structs, classes, interfaces, functions etc, across all platforms for which docs were installed.
Anything that was available online, official or not, was inferior to that. I'm not sure if it was deliberate, but it significantly hampered the utility of pirated copies of Visual Studio - since MSDN docs would require a lot more CDs than the software, most warez releases stripped them out. And in the developing world, where such pirated software is readily available on physical CDs sold by street vendors, they would usually be priced per CD regardless of what's on it - so a complete VS+MSDN bundle would be a lot more expensive, and thus in relatively low demand, and not widely sold.
Heh... well, I am old enough to remember the offline MSDN - which was great, and the rough transition to online - which got better, eventually... (and the rise of StackOverflow makes more sense in that context) but then at the beginning of the "cloud-era", IMO, it got worse again - to the point that I was constantly complaining about blog articles by MSFT employee's that really should have been folded into the actual documentation/KB instead...
It's a hard sell to tell an IT decision-maker in a different team/group that you need to configure things "just so" (think TechNet versus MSDN for configuration/operational articles) when all you have to point them too is a non-official blog post...
(Don't even get me started about the quality/out-of-date materials for things like Dynamics 365...)
It's mocked, but the underlying observation is astute.
In the personal computing world, first parties can't build enough user software.
Furthermore, software availability and reliability lag third party developer and development ecosystem health. A bad experience doesn't hurt the platform today, it hurts the platform in 1+ years.
And perhaps even worse, steps to address it take effect over a 1+ year timeframe as well.
Apple's been able to leverage iOS market share into papering over the desktop reality, but they're going to find the emperor has no clothes real quickly if anything about that calculus shifts in a bad way.
If you recall, back when the first iPhone came out, the idea was that Apple itself would be the only provider of first-class software for it, and everything else was relegated to web apps.
It didn't work out for them back then, and so we got native apps and the store. But I can't help but think that Apple still sees it as a sort of compromise of their ideal vision of what the platform should really be like, and thus dev ecosystem evolution is mostly on the backburner. Just look at how long it took for Swift to appear, despite Obj-C being really dated by that time.
It's not really the size of the company. Anyone qualified to write good documentation can make better money, work on more interesting things, and advance their career by actually working on the code. Without a culture that rewards and values the work it doesn't get done.
Well, not everyone who is qualified to write good documentation wants to work on the code, nor would they necessarily be as good at writing code as they are at writing documentation. If you're writing API documentation, you need to be enough of a coder to understand what the engineers are talking about -- and what they aren't talking about but really should be! -- but that doesn't mean you need to be coding at a level where you could have a career writing apps built on that API, let alone coding at a level where you could have a career implementing the API itself.
It's the "culture that rewards and values the work" that's really the issue, I suspect. Apple certainly used to have a culture of good documentation, and I know they've hired good writers, technical and otherwise, over the years. It's actually kind of difficult to explain why their docs are the way they are, other than just not putting any real priority on the necessary work.
Reminds me -- it used to be that I could plug my Macbook air into a monitor and arrange my windows, and it would return them to that position whenever I'd disconnect and come back. That feature vanished as of ~2018 and you have to buy some app to get it back.
My Macbook pro still does this. Granted, it's a little wonky. If you alter the window in any way while disconnected then it might not return to the original location. It also doesn't preserve any new desktop environments created on the external display.
That actually sounds good. When you pay for something it implies that you might stop paying for the thing if you’re not happy which means the seller is likely to work hard to make you happy.
I would love to have paid version of most of the apps/sites I use. Not ad-free subscription but paid version where I can be the unhappy customer when I am unhappy.
That's a bogus claim! The MSDN documentation has always been freely available. The subscription service included all of Microsoft's software editions for development purposes and that's what subscribers actually paid for.
The documentation of software packages, APIs, and driver kits was freely available online.
> It was originally available exclusively to subscribers
No it wasn't - the subscription service shipped CDs (and later DVDs) with technical articles, updated SDKs and the like. The actual documentation was always included with every Visual Studio version on the installation discs.
I remember quite vividly the "joy" of re-installing the latest version because the documentation format was incompatible between releases and you could either reinstall the new version from disc (which took ages) or convert the already installed one (which also took ages, but not quite as long as juggling 4 CDs - it had to "rebuild the index" or some nonsense like that IIRC).
So if you owned a physical copy of any Visual Studio edition, you also had the documentation and thus no need to subscribe to MSDN (apart from the technical columns, SDK updates and the magazine, which any reasonable boss would allow you to read during work hours).
That's a bit unfair. The web is what made it easy to publish at no cost, CD's still had mail and print costs associated so it made sense to send documentation with the software packages it... documented.
Most recent post is "Attributed Strings with SwiftUI" which is something I was wondering about. There's plaintext TextEditor view, but for rich text editing the impression I've gotten is to either fall back to something in UIKit or do it in a WebView. Will check this post out tonight, it might not change anything but I'd at least like a better idea where things stand in SwiftUI.
Yeah, for rich text you need to wrap a UITextView, there's currently no other way to do that. Also, if you have a large amount of text, TextEditor won't cut it either.
Even displaying rich text (non editable) is a wee bit tricky and severely under documented.
For a small app I recently just wrapped SlateJS in a webview and passed json back and forth. Slate is pretty nice but it would be nice to use a native solution.
Apple figures developers will still pay them $99/year even if they provide them with poor documentation, and unfortunately, it looks like they're right.
Apple: There's no official documentation for this, but here's a haughty forum response from an unaffiliated volunteer sycophant directing you to the extant superficially-related documentation.
I believe someone like Paul Hudson and the work he has done can influence a language's adoption by nearly an order of magnitude in the language's infant stages.
I released a Swift 1.0 app back in 2015, and continue to provide irregular updates for it but still churns some decent income (to me). If not for him, I really don't think that spark of enjoyment would have happened. What he provided was two-fold: an enthusiast to Swift and the iOS environment, and also as a teacher and big source of documentation.
Unreal engine is like that, except with fewer third party tutorials. It’s getting better but the c++ docs are almost as bad as having nothing. Some of them only have comments like “maybe refactor this” as a description, and the community wiki was taken down recently too
Years ago I worked on the documentation for one of those big game engines. Previously as a "user" I suffered a lot with their physics system, and there was a big gap about its performance and best practices. After a long research in the source code and emails back and forth in the company I was able to fill those holes. My motivation came completely from within me, because absolutely no one in the company seemed interested on fixing the docs. It's the least important thing in most of these big companies.
stupid question : but is there any specific reason why swiftui is not open source ?
I am working with jetpack compose these days and it is both open source and documented. I am not sure how I would work with it without that, it is quite a big departure from the legacy ui api.
I wonder how much of an advantage it is practice ?
It is one such toolkit among others, like React or Compose. It is different from making the whole OS open source.
I guess that since the benefit would be to make third party devs job easier, the incentive is not that great for apple .. devs will write mobile apps even if they have to write them in assembly.
Yes please. Finding a “see also” link to one of those is the best, because you know it will actually show you how to use it. Otherwise you’re probably on your own.
You could read through that and all of the linked pages and still have no idea how create a preview. Want to preview it on a particular device? Well, I can see there’s a PreviewDevice, it’s initialized from various kinds of strings, and absolutely no information on how to apply it.
At least you can read the code, Apple's libs are closed source. You have to resort to reverse engineering techniques to fill in the documentation gaps.
That's a very good point. Reminds me of the bad old days of .NET (pre 2.0) where the documentation was a bit shit, and you ended up relying on Reflector to figure out wtf was going on.
Makes me fell a little better knowing that professional iOS developers are having a similarly hard time with this, I was starting to feel dumb about it. I'm reading the docs, why can't I figure out how to use this?
Absolutely. I’m a CS academic writing “real” code for the first time in 20 years. It’s really reassuring to hear that Marco Arment is also googling for the same SwiftUI tutorials that I keep falling back on.
At some point I had to read through some issues on the Firefox and Chrome issue trackers in relation to rendering on macOS. I kid you not more than once I read someone saying something along the lines of "No idea how this works, lets ask some Apple people at the next conference".
Has anyone else noticed that Apple has been slowly moving away from the long-form guides that were helpful at explaining core concepts? I remember once seeing a comprehensive guide on code signing, but over the years it appears to have been scrubbed from their documentation resources. In its place is a much less helpful (but prettier-looking) guide.
In comparison, I've noticed Android has FANTASTIC developer documentation. I've found full guides for everything. Even esoteric classes that are rarely used have at least a little bit of documentation.
Android HAD fantastic documentation, just like Apple had 7/10 years ago. It might not be overly apparent just yet to everyone, but Android documentation is slowly following the same path as Apple documentation, where the experience is slowly degrading, but since it was so good a few years ago, that degradation didn't creep everywhere just yet.
My coworker and me are already starting to feel the pain on various core APIs, the latest being notifications, which according to my coworker had 3 full revision, and finding documentation for the last one is hard. Storage (with Android 11 modifications) is another place where the documentation is starting to get stale. Those are not the only APIs were the documentation was poor.
In my opinion, Android documentation is at the same place iOS documentation was about 5 years ago (before they started removing entire pages from the documentation) : overall very good, but a few places were it's not up-to-par or downright horrible. I don't expect the quality to improve in the future.
Even 5 years ago, I felt that Apple's documentation was way worse than Android's.
I wonder if there is a good way to measure documentation quality...I suspect such measures will require techniques borrowed from user experience research.
Yea, i think that's correct. documentation is just another product, no different than other software.
so basically you can start asking with very common user reasearch questions such as:
* who would use our documentation?
* what would our user need the most from our documentation?
I wonder if this is on purpose and that some companies receive good documentation so that competition is kept at bay. Does Google offer some sort of training packages for Android or you can get a loan dev that knows all the quirks? I've seen this with other companies where documentation is poor on purpose so they can make extra money from training.
I don't think Google does consulting or specialized training like this for Android.
For Google Cloud Platform, they partner with other companies (like the one I work for) to help with GCP setup. This partner program was started in the last few years, so I don't think they were doing this for Android back when Android development was new.
Also, the company I work for spent a lot of time building Android apps for Fortune 500 companies, so I feel like I would have heard about it. Our clients would have benefitted from having Googlers build Android apps and train people!
I feel like Android 11 is in a weird spot. Its a covid release and they didn't have their IO convention this year either. Seems like a lot of the big documentation dump is harder to find.
I'm seeing notifications as a feature fail on my android phone too. Apparently there is simply no reliable way to get a notification at a particular time (e.g from a todo app) anymore. ON A PHONE. THE THING DESIGNED TO BEEP/RING/NOTIFY YOU OF THINGS.
Because of all the junk they've added re: battery optimization, "Adaptive AI" notifications. Even after disabling much of that, it takes a 3rd party app to get notifications reliably.
Yes! Apple used to have Technical Notes that were a deep dive into how the OS is implemented. They were super helpful in troubleshooting and optimizing for Mac OS. They haven't published anything like this in over a decade.
I suspect someone took "hiding implementation details" too seriously, and now Apple never talks about how anything works (it's all magic). You only get function's signature, and "documentation" that is basically just the function name with added spaces between words.
Why in the world is this a random undiscoverable post in the (terribly designed) developer discussion forums rather than a Technical Note in the documentation? It would have been a TN in the past. In fact that same engineer wrote a number of old Apple TNs.
It's clear even to some within Apple that there's a need for more and better documentation, but some pointy haired boss in upper management seems to think the current situation is fine.
It might even be in their interests to drive away all but the most dedicated developers. After all, they have more apps than they'll ever need, the problem is always quality.
When I worked at Apple in the mid 90's, DTS had to hire someone to go around to every engineering team to collect what they had change so we could write a tech overview of an OS release, otherwise no one would have known what changed. But then was when Apple was going out of business.
There are good reasons to hide the implementation details in documentation. The primary being it’s easier to keep the documentation up to date, our primary topic here. Many languages even publish class interfaces but not necessarily implementation details.
That said, a couple of example code snippets on using the interface wouldn’t hurt.
It’s always the null cases that get you... I suppose if “up to date” was the only requirement I would agree. But in reality there are many competing requirements which is why there are many degrees of documentation. Obviously internal and external documentation will be different too.
The reason to keep implementation details out of the docs is that people will rely on those implementation details, and then when their app breaks, they won't even think of looking at the documentation for updated implementation details. After all they probably have the old version all but memorized, and the app may break in a way that isn't obviously related to the implementation that changed.
I once owned every copy, of every generation of "Inside Macintosh."
I agree about the Android docs.
However, in defense of companies that don't like to have too much documentation around, I can tell you, from personal experience, that writing developer docs is hard, as is doing developer support.
I was a Mac beta tester back in '83, and still have a copy of the pre-release "Inside Macintosh" mimeographed the day after the original programmers wrote their drafts, filled with penciled in corrections and in some places pages of hand corrected notes. Reviewing a formal copy after edition 2 or 3, I was surprised to see a reduction in information quality and some of the key information from the penciled in notes completely missing.
The original Inside Mac was 3 volumes, after their initial printing of the "phone book edition" - all three volumes in one thick soft spine binder.
I really need to take the time to scan my copy and put it online. It's got ballpoint pen corrections from the Apple Engineers telling the beta testers various fixes.
Yes, and this is a really shame. Several years ago I was able to become an iOS developer almost completely by reading through Apple's docs and then building a couple of projects on my own. I had a checklist of the programming guides to work my way through from Objective-C, to App Programming, to view controllers, and on. Over the years I found it more and more frustrating to truly understand new frameworks as the documentation changed. iOS development is now a small portion of my job and the lack of good resources is making it hard to stay up to date.
My guess is they’re realized documentation is a huge cost center and even their own technical writers are overburdened by the churn of deprecating APIs and changing best practices. It’s worse then the JavaScript community.
I find this business decision fascinating because a good portion of their App Store revenue comes from developers. One would THINK developer relations would be a priority at Apple, but it's pretty clear that's not the case.
It was one of things that I found unbelievable when switching from Android to iOS development. The developer experience is just so much WORSE on iOS. Sometimes, it's as if Apple is actively trying to annoy developers.
For API documentation, if you can specify what you intend to build well enough to build it and validate that you have built even approximately what you intended to build, documentation shouldn't be much more work.
And even when there's no documentation, or when it isn't enough, you can just always dive into AOSP sources and figure out whatever needs to be figured out. They've recently made this more convenient too: https://cs.android.com
No such luck for iOS. Best you can do is poke at binaries with a disassembler.
I have been frustrated many times after stepping into a system function on iOS, only to be greeted with a mountain of assembly instructions. It was one of the first grievances I had with iOS development, coming from Android.
On the other hand, it's been a great opportunity to learn how ARM works!
Based on the Android source code I've seen while working on Android projects, I think a good portion of the Android docs are generated by the inline documentation from the Android open-source project.
But on top of that, Google also produces high-quality long-form guides. Those are first-party guides, found at https://developer.android.com/. (Google maintains the Android developer site.)
Ah ok, thanks for the response! I've seen a lot of value in automatically generated docs from inline code. Perhaps that's a key baseline strategy for improvement.
Add then padding that with the long-form guides with concepts and examples.
Oh yes, I remember the programming guides! When a friend of mine and I wrote the text editor Tincta we spend days to go through the typesetting, font, glyphs documents. We didn't really use it but we learned so much (we were still students and couldn't imagine how complicated all that is). Same for the maps and location APIs. You could really appreciate all the work and design that went into the APIs.
Now I feel some of that information is hidden in WWDC videos but it's not the same.
I also had good experience with the Android documentation, same (as the article stated) for PHP and most of Microsoft.
It's really a shame that a scrappy little company like Apple can't afford the resources to produce documentation, even if not for their own apps at least for the developers who write apps that cause their users to buy the hardware. Maybe when they can get themselves established in the market they'll have enough financial resources to invest in this critical area.
===
I never liked Ballmer, and really never liked the win APIs, but I fell in (technical) love with him after the much derided "developers developers" dance he did. In that regard he clearly understood who buttered his bread.
OTOH Apple treats WWDC as the entirety of their developer outreach, when really it should merely be the cherry on top.
Apple at this begrudgingly allows developers on their platform as they slowly make their own apps to capture all the recurring subscription revenue as the logical endgame of its walled garden.
This is a common, lazy argument. Apple's bundled apps are typically MVPs rather than best of breed. For me an MVP is perfectly fine for my photos and video editing while, say, for calendar and address book I use third party apps.
I doubt anyone would claim that Pages or Numbers are any sort of competition for flagship apps like Word or Excel, while at the same time they don't even break new ground like google docs did (yes, I know it wasn't the first either).
And perhaps Apple will get its act together on its subscription services but so far they aren't world beaters either, and never have been (going back at least as far as eWorld in the 1990s).
I'm sensing an assumption that Apple needs their in house apps to be best of breed. I'm not an iOS or macOS user, but I've worked on systems over the years. It really seems like they're happy to let someone get popular to identify the niche that needs to be filled, roll an MVP to cover it, and kick out the originators with no real excuses.
It's like they're still focused on hardware development and the software is just things users want to do so let's have an app only as needed to retain users, ish.
I am an iOS and macOS developer and user and it doesn't look that way to me at all. (FWIW I use their hardware because IMHO it sucks less than the alternatives; I'm no special fan).
Actually this part I agree with 100%:
> It's like they're still focused on hardware development and the software is just things users want to do so let's have an app only as needed to retain users, ish.
And I assume this hardware focus is why their subscription options have been a mixture of mediocre and worthless.
But this point, while a common trope (and even with a name, "sherlocked"), I have't really seen it much in practice, especially since OS X rolled around:
> It really seems like they're happy to let someone get popular to identify the niche that needs to be filled, roll an MVP to cover it, and kick out the originators with no real excuses.
I haven't seen much evidence of this in the real world. Even in the case of the Sherlock app they made a more powerful tool and still left room for third parties. They don't make much on their own software and their MVPs really are basic.
Apart from a few marquee apps in the photo/video space they don't really have a big app effort as far as I can tell from outside. I don't know how good those apps are either.
In the end they want to save on r&d / market research costs. In Ye Olde Times, Apple would go on their own and ask themselves "how can we make an improvement in the lives of our customers?"... the answer were iconic, revolutionary products (iPod, iPhone, earpods) that outright created entire device classes.
Now? The only thing in focus is rent extraction - App Store cuts -, recurring revenue and vertical integration. Anything not contributing to that gets atrophied (documentation, as mentioned, or Apple Server) or put on life support (essentially the whole rest of the ecosystem, including for all too many years pro-level hardware). Innovation? Why should Apple take the risk and improve their core product with features that won't get used? They're letting third party devs pick up the slack and buy up or clone the most successful things.
They're still better than Microsoft as they discovered that people are willing to pay a hefty premium for devices that have security and privacy first class members at the priority scheduling for new features (especially compared to the utter shitshow that Google has allowed Android to become by not cracking down on vendors), but innovation that doesn't give them a direct cash profit simply does not happen any more.
> Now? The only thing in focus is rent extraction - App Store cuts -, recurring revenue and vertical integration. Anything not contributing to that gets atrophied (documentation, as mentioned, or Apple Server) or put on life support (essentially the whole rest of the ecosystem, including for all too many years pro-level hardware). Innovation? Why should Apple take the risk and improve their core product with features that won't get used?
well, thats the system we live in; companies are chartered to make profit...
to be honest, im surprised we get even the current level of support and innovation from apple that we do... i think in the long term though, this will only hurt apple, as other alternatives will be more plesant and easy to develop, the only thing keeping apples controlover devs will be its vice-grip on the appstore...
Yeah, and if you had the balls to make something you thought people would like, you sure as hell wouldn't call it a common, lazy argument, because you'd do everything you could—which is very little—to protect yourself from being cannibalized in the software industry.
Jokes aside, the point would be more compelling if the Apple apps at the top of the list all were competing against the apps being searched for, and if they included searches for apps that didn't provide functionality Apple did. The algorithm as I see it from the article is that the #1 popular app comes first. Of course Apple takes the top spot ... this is unfortunate winner-take-all promotion that in fact the entire software industry actually wants regardless of what they say or gripe about on medium (only upstarts complain, which ceases the instant they make it big).
So, then the #2-#k spots are apps by the same maker, which both serves to help the user discover other apps they mightn't have otherwise searched for (promoting use and engagement, and the app ecosystem per se), and helps persist the winner-take-all business model. By only promoting apps by the same manufacturer it maintains some odd definition of relevance.
Then after a run of same-manufacturer apps, we get back to #k-#n organic results. The user can very obviously and very easily pick out the fact that up to #k is pushing discovery, and that below there are the results they wanted. It's actually not a big deal (actively harmful) because of the irrelevance of the #2-#k results.
So, if they had bothered to include information on apps that Apple doesn't compete against (instead of producing a 1-sided story), for which there is a manufacturer who produces a very wide variety of apps, I wonder if you'd see the same type of results. #1 result being their super popular app for the search in question, #2-#k being other (unrelated to the search) apps by the same producer, then #k-#n organic results. Clearly most app makers are one- or two-trick ponies so wouldn't have search results like this. But surely there are some?
I was shocked as a developer who’s worked with numerous languages and framework, e.g. Python, C#, JavaScript, Java, Go, etc. to look at Apple’s docs... such a mess.
It looks like a lot of this mess started with Swift introduction. While Swift is cool and everything, it causes lots of confusion. Not only that documentation is not in sync but also many existing training materials ate in ObjC, there is legacy ObjC code and libraries. It's like they flushed all their ObjC history for this shiny modern experiment which may pay off long term but was quite rushed.
I swear to the gods of Cupertino I am not trying to start a flame war, but -- Apple fanboy though I am -- I recently started taking a look at Flutter and was absolutely floored by the difference in the state of documentation between the two. Leave aside all talk of the viability of cross-platform development. That's not what I'm talking about. I'm just talking about the developer experience of working with the documentation.
At my work there are two of us programming in Objective-C for our iOS apps. We lament that Apple seems to hate its developers. In my most dejected moments, I think of getting out of mobile development entirely, or diving deep into Flutter and getting a job doing that.
You are totally correct- and the worst part is, it hasn't always been this way. I've been doing iOS and Android development since the days of iOS6, and for the majority of that time, I've found iOS documentation to be significantly more useful than Android's. Recently it has flipped, and it has truly come to a head in the release of iOS14, where many documentation pages still mark live APIs as Beta software. It's so frustrating, and it is so much worse knowing that the developer experience used to be so much better.
> We lament that Apple seems to hate its developers.
The joke back then (well over fifteen years ago, pre-iPhone) was that Apple is very user friendly, but that developers aren't users.
It's interesting to see that that hasn't changed since then though, you'd think that with all the iPhone money they would've invested a bit of it in developer documentation.
Out of curiosity, how's XCode these days? Back then it was a rather scrappy team, but it still beat Metrowerks' CodeWarrior.
Well, I like Xcode. But Apple keeps making changes with every version, and some of those changes seem to be for no good reason. You get a kind of muscle memory after a while, from using your IDE. When a button is moved or removed, or a menu is changed, it adds friction to your day.
Also, I got bit with this thing they did for the new ARM chips in the Macs. Our script to build a fat binary (device and simulator) for a in-house framework broke, and we couldn't add the simulator anymore. That took a lot of tracking down to fix. It's constant aggravation like that that wears on a person. Last year, we had the 3rd-party mapping software we use break, because -- as best as I can tell -- Apple changed the implementation for drawing. That was a pain in the ass to track down, too.
I wasn't kidding when I wrote that I was a fanboy. But the other day I was thinking of Steve Ballmer, years ago, running around on stage like a sweaty lunatic -- "Developers, developers, developers!" I mocked him then. Now I'm sorry I did.
I literally googled a few hours ago for "Why is Apple documentation so shit?"
I mean, look at SwiftUI. Conceptually it's great, but it is also fucking buggy as hell, and I think one of the main reasons is that the developers themselves don't have good documentation available. The best documentation so far I found is this, but it's third-party: https://www.objc.io/books/thinking-in-swiftui/
SwiftUI is not great in any sense, other than looking great to people who've never written non-trivial software. When your criteria for 'great' is whatever 'content creators', 'software journalists' (email newsletter 'creators') and apple's marketing team pump out this week, 'great' is anything a marketing firm puts dollars behind that seems 'cool' and 'fresh' and 'hip', or is it 'dope' this week?
It is quintessential form over substance - like Apple's fucking 'butterfly' keyboards.
SwiftUI is butterfly keyboards of software - wait until you want to write non-toy code with it, you'll be needing 'hack #235 by content creator #563' to make trivial features possible.
I've actively made an effort to learn SwiftUI this week so I can write my software quicker. I don't want to spend hours on displaying some styled list in my apps, that should be done in a few minutes. SwiftUI allows for that. Once all the bugs are gone, that is. So far, I've spent a lot of time on SwiftUI's bugs. Luckily, you can always dive down to UIKit if all else fails.
SwiftUI brings concepts from React and Flutter to the Apple ecosystem, which is great. It's especially great for people writing non-trivial software, because we don't want to spend our time on doing trivial stuff.
Ah, we are so lucky to have a framework full of language features that only it uses and an ability to drop down and learn a whole other suite of frameworks that work completely differently to achieve the same task!
I've been so lucky to have to learn near a dozen programming languages in the span of less than a decade to write CRUD apps that appear on screens and do the same thing on each platform slightly differently.
I only hope to be more lucky in the decades to come, maybe I'll have to learn two dozen new languages and three dozen new frameworks to write CRUD apps that show up on computer screens.
I am 'doing' real software - I saved up my money writing CRUD and quit as soon as I could afford to.
What I am personally doing in no way negates the fragmentation that is present. SwiftUI is the latest contributor to never-ending CRUD hell and I am merely informing the young and impressionable, that SwiftUI is not your friend - it is your anti-cross-platform, proprietary, closed source devil spawn (being dramatic for fun :)) and if you ever want to start solving real world problems instead of learning the latest framework that does what we did 20 years ago but 5% better this time, you better listen real careful to annoying debby-downers like me, Joe Armstrong (RIP), Rich Hickey etc who got fed up with the corporate matrix and went a different way.
I had the pleasure to attend a talk given by Joe Armstrong. For some reason he was always looking over to Phil Wadler, apparently looking for approving nods, but there were none to be found :-)
I hear what you are saying. I also find it unfortunate that something simple like UI is so fragmented. But then again, maybe UI is not so simple after all. The current paradigm that SwiftUI copies and evolves is that of React, and it just didn't exist 20 years ago. Funny also that this new paradigm was invented for the web first. While a lot of web stuff is crappy indeed, this is one of those examples where it produced a superior paradigm that is now copied and evolved outside of web as well, for example by SwiftUI, also by Flutter.
Is it progress, though? If the React paradigm is so much better, you'd expect some kind of UX renaissance stemming from its adoption. Instead, we're still struggling with Electron-based apps that are "prettier" but less productive than what we had 20 years ago, back when they were written in UI frameworks that barely even had any data binding at all.
SwiftUI is “great” for a calculator demo or a to-do list app. Otherwise it’s just a gimmick, but Apple had gotten anxious about ReactNative and had to make something palatable for the webdevs... Although making SwiftUI mandatory for home screen widget extensions is very concerning, and on the long run they’re probably shooting themselves in the foot by pushing this buggy toy framework...
I've been a technical writer for ~8 years (3 at a startup, 5 at Gooble). I don't know Apple's situation but here's my guess:
> Is the documentation team too small? (Likely.)
Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it's safe to say how important it is for job success) yet technical writing is almost always understaffed, no matter what size company you have. Part of it is that it's really hard to show a causal link between the docs we create and developer success. I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links at the bottom of pages, followed by an opportunity to provide freeform feedback. If developers started using those consistently and leaving testimony about how the docs helped them it would be a lot easier to prove the value of docs. This is especially true when you operate at a big, platform-level scale, as is the case on https://web.dev (what I work on) and these Apple API docs. Pageviews give us a rough idea of the demand for certain ideas but don't tell us anything about whether our docs are actually useful.
(As an aside, in some situations it's easier to justify the technical writing team's existence; e.g. your technical writer specifically creates docs in response to support requests and the support team is able to just link customers to the docs rather than re-answering the same question over and over; or you have access to "customer's" code and are able to show that they are following the best practices / use cases you mention and avoid anti-patterns you warn about)
I'll leave with a suggestion because I don't have a horse in this race. If this situation is so bad; your best option might be to create a community-managed MDN-style resource for the Apple ecosystem. I would suggest focusing it on 1) API reference documentation and 2) examples (MDN puts the examples within the API reference pages, that would probably work here).
Another route could be more of what these people are already doing: make a lot of noise until Apple realizes how bad the situation is. I imagine if you can prove that you're leaving their platform because the situation is so bad, that might wake them up.
(No disrespect to Apple people; I know how tough this situation is; just trying to provide constructive feedback for the broader community)
> technical writing is almost always understaffed
> it's really hard to show a causal link between the docs we create and developer success
Amen to that. IMO good documentation is incredibly valuable, but not in a way that aligns with business priorities. At my current job, we hear, repeatedly, that our documentation is poor, and that we need to improve it. Execs echo this sentiment, but the status quo doesn't budge.
Internally, we have about a 10:1 engineer:tech writer ratio (in a small-ish org--I assume the gap is even wider in larger orgs), and the writers are all generalists, covering every product from top to bottom. In practice, this means that engineers are asked to draft the bulk of documentation, and the writers scramble to at least copy-edit it.
Engineer-drafted documentation often isn't great, unfortunately, for several key reasons:
- Writing software is very different from using software. Engineers often don't use their own products, and writing about something you don't actually do is hard.
- It's very easy to omit details that are important for novices when you are an expert. Engineers usually have a great deal of knowledge about their own software in their brain already, because they wrote it, and cannot magically forget everything they know when asked to write documentation for someone who doesn't have that knowledge already.
- Writing effective, clear prose is hard, especially when writing about complex technical subjects for an audience with varying skill levels. Engineers don't spend the bulk of their time writing prose, and it's often not their strongest skill.
Personally, I have a mix of both skillsets because of a weird career path, but while I actually like writing documentation and am arguably better at it than writing software, there's no good reason to pursue that path: I can easily get double the salary in an engineering position as I can in a writing position, despite being a rather mediocre engineer. So I do software engineering :shrug:
It's also very hard to get in the minds of the developers who rely on the API/tool and create documentation that mirrors their mental models, background, language usage, etc.
With Chrome DevTools (I wrote/maintained pretty much all the official docs for about 3 years) it was a bit easier because I had a huge repository of direct user experience to draw from: the thousands of Stack Overflow questions about DevTools
> the writers are all generalists, covering every product from top to bottom. In practice, this means that engineers are asked to draft the bulk of documentation, and the writers scramble to at least copy-edit it.
This seems like an organizational/staffing mistake. In other engineering orgs you'd see these roles filled by applications engineers, who dogfood while evangelizing the product and writing its technical documentation. Ambiguity or questions are handled by conversations with the engineers that built it.
I do think hiring application engineers with that kind of job description is one solution, but so is having a larger number of technical writers so they don't need to be generalists.
> I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links at the bottom of pages, followed by an opportunity to provide freeform feedback.
Whilst this is great, I think most people perceive documentation differently. Rarely does documentation delight me in the sense that I'd leave feedback. Generally, my interaction with documentation is one of "It works as expected"; "pretty bad but I still managed"; or "bad, didn't help, or didn't exist".
The thing that has the most effect on my is the last one. That is what will get me to drop a system. The first one "it works as expected" comes with a little but of surprise and delight. But, perhaps paradoxically, even though it surprises me, it still only meets my expectation. With a 'was this helpful' prompt, I'd need to click "it was helpful" on every successful search of documentation I ever do. This seems still too unremarkable for me to explicitly mention it was helpful.
Yup I know it's a tall order / unrealistic but I'm just trying to provide context as to why documentation might be systematically underfunded (lack of causal chain proving its value). Your response is totally understandable but it also demonstrates why the situation probably won't change any time soon.
establishing a DSAT metric is still powerful. Lifting a key feedback metric from "this is bullshit" to "this is ok" is something you can sell management on
To be honest, was this helpful button is rather vague and I usually ignore it because it doesnt seem to be the right question or rather its a request for feedback I don't know helps me or not.
I advocate for "was this page helpful?" being the standard question across docs sites because ultimately it does reflect the purpose of documentation (to be helpful in one way or another, which usually means helping you complete a task or understand a concept) and because using the same question on all sites enables us to benchmark and compare. I once ran an A/B test on the same page where 50% were prompted "was this page helpful?" and the other 50% were prompted "was this page useful?" and the results were different to a statistically significant degree which suggests that even minor rephrasings skew the results, so we need to all use the same terminology.
> its a request for feedback I don't know helps me or not
Yes I'm aware that readers aren't incentivized to respond which explains why it's rare to get higher than 5% response rate. This situation is a microcosm for documentation's overall problem: we can't find incentives for people to voluntarily and consistently confirm the value we provide and we don't have any other means to prove the causality.
"Part of it is that it's really hard to show a causal link between the docs we create and developer success"
Yep, high traffic to a dev doc web page is ambiguous. Is it because it's really good? Is it because it's bad and people keep coming back trying to understand it? Or is the documentation fine but the API being documented is just hard to use?
We get 1-5% response rates (which is normal; I've done this on a few sites now) but we have enough scale where we're getting enough feedback that I can use the data to identify the worst docs. The basic methodology is to prioritize the pages with the most pageviews + lowest helpfulness scores. Of course there's a risk that we're prioritizing our work based on data that isn't indicative of our overall audience and due to the general nature of the question ("was this page helpful?") we also don't know how exactly the doc is unhelpful but in practice it's usually easy to make an educated guess (e.g. one of the Lighthouse guides is very low rated, and when I checked on it recently I discovered it's just a stub with very little guidance; so the educated guess is to add more guidance to the page; and then a few months from now I can see if the ratings have improved). Another good pattern is to provide a freeform textbox for feedback. The only reason we don't have that is because Gooble considers it PII and I have to jump through hoops to store that data properly.
As someone who was in the so called "DevOps" position for years, I'm slowly becoming tired of asking management for "give me a technical writer, even half-time, instead of another dev/ops person" :(
I'll admit that I'm pretty bad at formal documentation myself, but I've been wanting to improve that lately. So as a technical writer do you have any suggestions/links to material for learning the trade or even some sort of formal training courses for professional development that I can pass to my employer?
> I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links
And when you do this, DO NOT serve up the feedback form/popup from some advertising domain, otherwise developers with ad lockers (many, if not most) won't even see it.
He was trying to find out whether it's safe to call a particular iOS API function off the main thread. Obviously, the docs didn't say. He googled a bit and found a support forum where someone had asked. An Apple engineer responded: "I don't know, but I'm looking at the code, and there sure are a lot of locks!"
In some cases the documentation just plain wrong. Core data can be confusing, but worse with wrong documentation. I've had an open radar about the merge policy documentation for over 3 years and nothing has happened, even after talking to a core data engineer at WWDC in 2018.
I have been trying to optimize a initContainer written in NodeJS and one of the experiment I am trying out is to rewrite it in .NET Core and Microsoft's documentation has been pretty good - it is clear, well organized, gives you examples for each API and there are how-tos for things that people typically care about - the architecture docs linked from here for e.g. https://docs.microsoft.com/en-us/dotnet/
I find the Python docs and tutorials good as well. But that's to be expected for mature language/ecosystem like Python.
Good documentation is a lot of work and skill and it's a thankless job for the most part. So it's really amazing when organizations / OSS communities get it right consistently.
Microsoft has put lots of effort into their docs in the past couple years, and it's pretty great.
Under the "Version" dropdown you can flip to see the same docs in a specific version or platform (Framework vs Core), and this is pretty helpful for porting/upgrading code, as well as coming from a Google search or Stack Overflow link -- you can easily get to the docs for the version you're working with.
The other great thing they've done is published all the .NET code on https://source.dot.net, so you can dive into the code for ConcurrentQueue<T> [1] for example. I sometimes find looking at the source is a faster way to answer a specific question about how something works vs reading through several pages of documentation, where the nuance I care about is noted in a "Remarks" section which is easily missed.
Yes, the version dropdown is a godsend especially for .NET as there are many variations - If I want to see if the API exists or is different on say .Net Core vs .Net standard this makes it a piece of cake.
Also wasn't aware of the source browser - some questions are best answered by - use the source, Luke - and you might get better ideas for your own code from there :)
Personally I keep a .NET decompiler on my taskbar. I was about to say I like being able to find all references and usages of internal variables, but I see now the site does a pretty good job. I also like directly seeing how my code utilizes the library functions (not just the .NET libraries, sometimes nuget packages too). The decompiler also removes ambiguity of "what code is actually being ran". ILSpy has worked nicely for me, it has the extra perk of having nice integration with LINQPad (another must-have for .NET developers)
ILSpy + LINQpad is my go-to as well, and I actually still use ILSpy more often than source.dot.net. It's nice to be able to send a link to someone else though, and the site is well done, fast, and has a great domain. :)
Is there an offline version of that documentation? One of the best things about Java is that you can install the documentation package (depending on your distribution, it's something like java-11-openjdk-javadoc) and the source code package (something like java-11-openjdk-src), and have an offline copy of the full documentation which you can open directly in your web browser and IDE.
Having run into something similar just recently [0], having any documentation is still (slightly) better than no documentation at all. As a stark example, macOS has a built-in sandboxing CLI tool called sandbox-exec (originally called Seatbelt), but the man page simply says it's deprecated, as far back as I could find them. Mind you, the same tool is used heavily by macOS internally, and has been around ever since Leopard [1]. Some of the best documentation is by engineers at Google, Mozilla, and others, who have just reverse engineered the thing.
Marco is right about PHP's documentation. I've felt for a long time that the quality documentation PHP provided played a major role in the language's success.
Every method and object needs five things: 1) what parameters does it need to be used or created 2) what values does it return if any 3) a simple description of what it does 4) a simple canonical example of it being used that can be copy/pasted as a template 5) notes from devs which can help elaborate on the above.
This is pretty basic, but where PHP nails this, so much other documentation completely ignores one or more parts. Finding a return value in Python docs usually means reading through a paragraph of text or using dir() from a command line. Figuring out how to use a Javascript Object can often mean jumping around MDN looking for a reference, unless the feature is super new, then all you might get is a signature. Android documentation will give you everything but examples.
Objects and functions are like parts of an engine. You need to know what each piece is used for, where it goes, how to install it and the way it all fits together.
It's true! For me, PHP's docs were an amazing on-ramp to becoming a developer "I just need a function that does something like...". A lot of the language design is annoyingly inconsistent and hard to use, but even in 2005 there were clear explanations on how to make it work.
As an experienced engineer, if I'm handed a well-designed but poorly-documented API, I can usually guess the intent and make it work, at the cost of working more slowly. But a junior engineer will be completely stymied by insufficient docs, regardless of how good the software design is.
I guess, in summary: good docs can make up for bad code. But good code can't make up for bad docs.
PostgreSQL’s documentation is also amazingly well done.
There’s also HighCharts. But not the documentation, rather the fact that I almost never felt like I needed any. The API was just so well done that you didn’t need any. That was my experience anyway.
I wanted to print out the Postgres documentation to have a physical copy and then my jaw dropped, realizing I would need to print out 7 double sided 50 page booklets if I wanted to do this! 300
in the old days MySQL + PHP became a popular combination because they both had great docs. But Oracle has let MySQL's documentation get worse and it's no longer the best
I had to work on a small MacOS app written in objective C at my last internship. The documentation was horrible. It was basically non-existent. I understand Swift is the primary language now, but wow, there was basically nothing in the online API reference.
Weirdly enough, this tends to be where Apple's docs are still good. They fall apart when you try to move on from it towards Swift & co.
Granted, _finding_ the ObjC old docs can be a pain in the ass, but it's possible. I've literally found answers to some of my questions in OS release notes and nowhere else; part of being an AppKit/etc developer winds up being simply knowing how to search.
Another complaint I have: depending on what era of documentation you need, you often have to qualify your searches differently - e.g, OS X vs macOS.
The only thing that might make Apple improve their documentation is if there was evidence that people started actually abandoning Apple's platforms.
Currently it seems there is a never ending supply of developers ready to gamble years of their careers on Apples Terms & Conditions, and while these same people usually eventually realize that there's ultimately no money to be made, they are replaced with a new generation seeking an AppStore paved with gold. Until that stops, the docs will stay piss-poor.
While I have often used a Mac for development and enjoyed it, I don't often actually develop anything for macOS or iOS because, well, why would I risk my livelihood on Apple's whim? They regularly destroy developer's lives with no thought or consequence.
There is a lot of money to be made working on iOS for big corp. hell, even small startups.
You seem to allude to indie devs though, so I can agree that it would be insane to attempt to go out on your own without essentially being a startup in your own right.
I can't get my head around why their documentation is so poor.
They should have all the resources in the world to recruit people that have proven to write good documentation. If open-source projects run by volunteers can have excellent documentation (e.g. Vue), why can't Apple?
Better docs mean a better developer experience which means more people want to (and are able to) develop apps for iOS which increases the value of their platform. It looks like a no-brainer to me to invest some resources into this to improve the current state of affairs.
Apple developers are a captive audience, they will pay their annual hundred bucks and develop for iShiny no matter how crappy the docs are. There are just too many rich users and clueless PHBs demanding apple development to miss out. If those reasons went missing and Apple really had to compete for developer mindshare, docs would improve.
Which leads to the solution: Quote a lot more for Apple development or don't develop for Apple, and as soon as the stream of app updates and releases dries up, Apple might react. But not before.
iOS is Apple's bread and butter, and they make good money off those developers. It's in their cynical self-interest to spend the money to have the best documentation in the game, and it would even pay off inside Apple, with better APIs and better resources for their in-house teams to develop against.
It seems like a genuine institutional dysfunction. Apple has a culture of secrecy (which is necessary) and a result of this is deep siloing of teams. How this leads to documentation being such an afterthought is murky, but I suspect that's the cause, rather than merely being complacent about their walled garden.
I can also do handwaving culture arguments like apple design in a minimalist fashion, so everything that can be left out will be, including documentation. But I don't like those, I hate to diagnose cultures I only read about.
However, apple is a business, and leaving out docs makes business sense and is an easy and straightforward explanation.
It's a puzzling omission, given that building App Store revenue is such a priority, and they feed the supply side in a number of other ways. I don't think they're doing it on purpose, they're just bad at it.
I think what is happening here is that the attitude of Apple towards normal users is spilling over to its attitude towards developers. Which is obviously a big problem, if that is indeed the case.
I don’t personally have much experience with Apple’s documentation in particular, but as a general topic, increasing the quality of documentation seems to be one of the least complicated ways to improve a platform. For all the complaints people have about how hype-oriented the frontend web world can be at times, it seems clear to me that there’s usually some correlation between hype factor and simple examples/clear documentation, and that this excitement can make people move to a new technology much faster. It’s really hard to understand why Apple wouldn’t spend the necessary resources to bring developers along at a faster pace.
I am 100% convinced that Stripe's success is at least partly due to their attention to documentation and design. Their documentation and knowledge base should be used in case studies on how to succeed as a saas.
Here's a contrarian view of this (deplorable) situation, from someone who developed for Microsoft platforms for years. The low quality of the documentation has two reasons:
* Protectionism: The poor documentation defends expert third party developers against competition from new entrants. It ensures a shortage of competent developers and so enhances the revenue of established experts.
* Low commitment: The publisher (Apple) is unwilling to make the functional commitments implied by good documentation. Once the documentation says "this does that" it's harder to change "this" to do something else.
In the distant past, Apple teamed up with the publisher Addison-Wesley to create and publish high quality documentation. They could certainly do so again, with A-W or O'Reilly or whoever.
But they won't do it as long as they have business reasons not to. They have sufficient control over their marketplace to refuse to do this and get away with it.
> The poor documentation defends expert third party developers against competition from new entrants. It ensures a shortage of competent developers and so enhances the revenue of established experts.
Why in the world would Apple want to ensure a shortage of competent developers — for apps on Apple's platforms! — or protect third party experts?
Why do they want dev skills to go at a premium price? For one thing, they do not have any shortage of apps coming in to their app store. They're no longer in the business of begging people to deploy apps. Instead, they're in the business of vetting the apps people submit.
Raising barriers to entry for new developers is a cost-cutting measure for them. And fewer apps on the store, even at the margins, is a revenue enhancer for incumbent app developers.
This may or may not be an explicit factor in their decision making. But it surely contributes to their lack of focus on docs: better docs will improve their profitability not at all.
Apple slowly wants to pump out their own apps that do everything to maximize their recurring subscription revenue. Why settle for 30% when you can take 100%.
Why would they improve the documentation? It's not like you have a choice anyway, you will have to figure out, since you cannot ask your customers to switch to another mobile platform... They really don't give a shit about developers. I'm a backend developer, their In App Purchase system is the worse API I have been unfortunate to work with (and it's much better than what it used to be)
Hah the nightmare to get CallKit working. The only thing you could do is take a working example application and step by step wrap your application around it.
Because taking your existing VoIP application and inserting CallKit behavior breaks in so many mysterious and undocumented ways that I really had to tell a client it wasn't going to happen with his existing application within the allocated budget.
Just to get the fancy Apple call screen!
And of course only FaceTime can take video calls straight into video from the lock screen, so you have to explain after it works why nobody can see each other.
I actually disagree completely. Your answer does not relate to my comment at all.
This is about “Apple losing the functional high-ground” (which they clearly had at one point) in terms of design, architecture and general “DX”.
All in comparison to its own previous high quality.
In terms of quality of products they still are best in their respective class IMHO. Security, usability and durability are still great/good enough. This has nothing to do with marketing.
Marketing is necessary to bring up as Security and durability claims have been debunked enough times. Perception isn't reality, but similar to Tesla and Jeep owners they have high satisfaction despite objectively poor qualities.
You only need to try giving your grandparents a iphone to realize usability claims are greatly exaggerated.
The n=1 sample sounds like a normal beginner that wants to buy high-end equipment for a new aspiration. Doesn't mean much. My n=1 is for unix architecture and reliability. Probably the same for many devs.
Big +1. Those docs are a big reason I found Phoenix to be so fun -- all my beginner questions were stupid easy to answer, and my more intermediate questions had guides and links to further study in the official docs.
It's deprecated, and there's no note on what the replacement should be. Xcode, however, has a hint to use the `run` method. This isn't documented anywhere. If I don't use Xcode, I wouldn't know about this replacement.
People speak about Apple excellent libraries, but a lot of these just lack in documentation.
Moreover, Apple will also _remove_ documentation of API they are not favouring.
And it makes sense, Apple is such a monopoly it can afford to have zero documentation, application developer would still need to get users where they are.
But honestly, it's probably more that it's expensive to have good docs, so this job is being optimized out.
Apple no longer gives a shit about developers because they don't have to. They ship as many IOS devices as the China factories can produce and dump trucks full of money keep lining up outside the front door. Why should they spend money on technical documentation, or better developer tools, or even the quality of their desktop operating systems? Those things don't make Apple money.
What makes Apple money is building pretty, locked-down computerlike appliances that are completely under Apple's control. I don't think Apple even sees developers as necessary any more, except the ones in their employ.
This isn't an apple thing. Its industry wide. Much of the good documentation that exists is stuff that was written 20+ years ago by actual technical writers and is still being maintained.
AKA the windows API/etc documentation, linux man pages, etc.
The vast majority of modern documentation is worthless autogenerated garbage when it exists. It lacks good examples, meaningful overviews and functional diagrams. In many cases its woefully out of date because someone rejiggered an API and didn't bother to even update the inline documentation.
One of the better examples of recent documentation is the core rust docs/books. Even then because the rapid release cycles no one publishes an updated "Learn Rust" book for every release, complete with boxes explaining what has changed since the last release. And god help you if you dig to far into the library ecosystem.
I think this is caused by one single problem. Documentation isn't sexy and no one is paying technical writers to do the grunt work anymore. Opensource is a large part of this problem, but the commercial guys have discovered they can save a few hundred thousand a year by simply not having a documentation team, and it doesn't appear to affect them much. A couple youtube tutorials and they are done.
You can see this in the evolution of software, etc. In the 1970's you got large paper manuals which covered every technical aspect of the machine/software. The users were expected to use their brains. Then in the 1980's it all transitioned to "user documentation" which was more focused on manuals that explain how to use the product, by removing the how it works part. Then in the 1990's it started moving to digital copies on disk, and the product came with a 3-4 page manual explaining how to bootstrap enough to read the rest of the docs. In the 2000's it all moved online and became more "marketing" than users guides. In the 2010's they stopped even that. Now you get a phone/software/computer your lucky to even get a piece of paper that tells you how to turn it on, charge it, or install it. Even ms doesn't publish a complete guide to all the magic swipes and keystrokes that are supported by their new shell.
Function description, supported version information, header-file and library file information, meaningful return code documentation, links to an overview of the system wait behaviors, documentation about what happens in low power situations, links to example code using the function, differences in behavior between differing versions, it goes on and on.
Can you point to something you think is better?
PS: I should point out, I have paper copies of the win32 api from the early 1990's that are falling apart from the use they got.
Arr, sorry I misread your comment. I am on your side when it comes to Windows API. But I am not sure if it's a thing of the past. Imo Microsoft is pretty good when it comes to documentation. The way of presentation can be improved, but I really appreciate it. I think it's a culture thing and that culture seems to be different within Apple... I think this is also visible when it comes to their app store policies....
That is a good one too, but its not in as bad of shape as my official win32 guides from MS. My copy of Volume 2 of the win32 reference has nearly as much tape as paper, although I haven't picked it up in probably 10 years.
edit: Holy crap, in an effort to find an online picture of the volume, i noticed that amazon is selling the slightly newer ones for over $800. Looks like I should have taken better care of it.
I looked at the example the article links to, and it's worse than it portrays. Not only is there no information on the requestAuthorization page, but the enum type used, PHAccessLevel, also contains no documentation! Apple, how hard is it to write the different values for an enum?!?
I have often seen people complain about auto generated documentation being worse than useless when that is not the case. It's not that the documentation is poor, it's that there is a complete lack of the other 3 kinds of documentation.
I wonder if there is a way to get Apple's attention. There's a lot of power in collective action. It'd be interesting to see what would happen if every developer who was unhappy with the documentation put in an email, a call, or a support ticket.
My other problem with Apple is the lack of PDFs. Apple has a bookstore, I should be able to download the whole of Apple's Developer Documentation on my iPad. I would prefer PDF because I cannot read a screen for hours.
Plus, the examples are almost always broken and don't compile. Broken samples and videos are horrible ways to teach anything.
I don't think Steve would have allowed this to happen. Developers are way too important part of the whole "where the money comes from?" question. He would have noticed the complaints before anyone wrote a blog about it.
Docs for the 68k Mac were abysmal. There was a collection of books entitled "Inside Macintosh" that were nearly impenetrable, and only scratched the surface of the elaborate class libraries. Instructions for creating "Hello World" on the Mac were dozens of pages long.
From what I've read, Jobs certainly understood the importance of software, but only great software. He didn't want the Apple ecosystem to become loaded up with crapware like on the IBM, or on the Apple ][ for that matter. So, if a small time developer couldn't write and distribute a crude but useful app, so be it. Favored developers probably didn't fare any better with the documentation, but help was a phone call away.
This was the "closed box" philosophy that I don't think has changed much over the years.
The irony was that "crappy but open" attracted more developers than "wonderful but closed." This is why apps such as assemblers for microcontrollers were written for MS-DOS. Essentially, even after the introduction of MS Windows, the ability to write for DOS provided a way to create and share simple apps.
I still have my copies of Inside Macintosh, I consider them to be examples of good documentation.
They didn't cover "class libraries". I don't have copies of whatever documentation was provided with MacApp, I do have a Think-C manual that describes their environment.
Thanks. I appreciate the counterpoint. I don't remember when class libraries became part of the Mac programming experience, but like you say it might not have been with the original docs.
Apple recently required that anyone using 3rd party authentication (google, fb, etc) in their iOS app, must also provide support for Apple ID signin. That is not an unreasonable request. I was able to implement the signin without too much difficulty. However, when it came to doing a server-side validation of the signin via the Apple API; it was an absolute POS blackbox.
Their documentation and server responses provided no indication of why the validation failed. I searched the docs and forums; it was clear that a ton of other people had the same problem with absolutely no clues into resolving the issue. So I just gave up on it. Total waste of time.
Have you considered using Qt? It compiles and runs native on macOS, the documentation is superb. You just let the Qt people worry about the Cocoa, Quartz etc. interface.
As a bonus, it will also run on Windows, Linux, Android, iOS.
Qt looks like an "operating system". It isn't really an O/S, it feeds off the underlying O/S, but to the applications programmer, it completely subsumes the O/S.
We converted a 500KLOC Win32 app to Qt (and macOS), and there is not one single Win32 API call left, except for an obscure font enumeration thing because we wanted to stay with our own PDF code instead of using Qt's.
Qt is not true Cocoa, even still - IIRC (and I think it was literally somewhere on this forum that I was corrected by a Qt engineer) they use the Cocoa things to handle some drawing code, but it's still their own stuff on top of that (they used to use HITheme & co before they modernized it).
It's why you'll see subtle differences on things like buttons.
The author is a podcaster and developer pretty much focused on Apple and mostly iOS. I think developing for other platforms is a total non issue for him and he also hates C++. I doubt Qt would be an option.
Say what you want about the npm ecosystem, but I've found that the most popular libraries to solve a particular problem are almost always the ones with the best documentation. It's natural selection: the ones that are easier to install/use get installed/used more often.
It's to the point where I expect good documentation, and will pretty quickly discard a library if the docs don't look robust on first inspection.
It's sort of bizarre to me that Apple doesn't know this, or at least hasn't acted on it.
I think they know it's bad, they just don't need to make it better because its their OS so they're the only game in town. Developer experience isn't why people write apps for mac/iOS, so there's not much incentive for them to invest in it.
Apple seems like they are willing to double down on SwiftUI/UiKit with Catalyst.
It's getting less simple for new APIs/features but at least Apple's docs have straightforward hierarchy, even with two separate languages. Duplicate APIs usually get deprecated, like the old ALAssets photo library API.
Try building an app in .NET. There are dozens of different breadcrumbs you can follow on the MS docs for varying versions of .NET, Windows, and frameworks with radically different feature parity and UI systems. Virtually everything you google when building a .NET app has to suffixed with a bunch of identifying information for which libraries and versions you are targeting.
Open source has a serious advantage in this regard because communities tend to congregate around project and documentation styles that are consistent with similar projects, so you already have an intuition for how to navigate a new repo. I find React Native documentation especially easy to parse, although sometimes missing features or examples.
OSs have it tough because their docs aren't tailored specifically to each framework and domain space. But maybe they should be. I think if engineers felt more like they owned their product's documentation, layout, and structure like at smaller companies, they'd be more inclined to make it just right. The SwiftUI specific tutorials are great.
For me, a large part of React Native's appeal is the docs giving me a clear path to make stuff and a fairly public development process. Sure it is also an extra layer of trouble, but I prefer the trouble I can engage with (RN) over the risk of being stranded in the unknowable (Apple).
True, and I do like this a lot. There's a great ecosystem, and the examples are usually pretty good.
But it's also just as easy to get stranded with missing features or features that aren't on both Android and iOS. I did a bunch of geolocation and mapping a while back and I had to write my own support for things like heatmaps. This was eventually merged into the react native maps library, but it is something that can happen if you're doing anything slightly exotic.
Is it really an asset to not have documentation for old frameworks or versions? Some people have customers on old hardware and legacy code using old APIs that they might need to integrate with, it's useful to be able to find out how that stuff behaves.
That's the thing, it's all still there, but it's abundantly clear based on the pages and the list of supported OSs/platforms whether you can use it, and what the new API is.
Even the videos at the latest WWDC have been really challenging. For example, the videos showing new Document Driven apps in SwiftUI never released their sample code as a lot of developers sought here: https://developer.apple.com/forums/thread/651193. They really just presented a glorified demo and a few slides.
Disclaimer: I work in Developer Relations at Google.
At most large tech companies (Google, Microsoft, etc) the documentation is the responsibility of the Developer Relations team.
Apple has always been an outlier: they never had a Developer Relations team at all. I've recently seen some job postings for DevRel @ Apple, but this is super new.
> Apple has always been an outlier: they never had a Developer Relations team at all.
Not sure if that is accurate, I just did a quick search for “Apple Developer Relations” on LinkedIn and found a bunch of people who’ve been in Developer Relations or Worldwide Developer Relations at Apple for 5 or 10 years or even longer.
I've been working on a very simple (but extremely useful) WatchOS project I'd like to keep under wraps for the time being, as I think it could certainly sell.
Apple's WatchOS documentation, however; is sparse at best, barely there at worst. It's been a problem with various Apple documentation for years.
I also have to agree, now most modern stuff is only mentioned at WWDC, while the older material is only available in the archive, with its replacement being just the "header" file/module listing.
I just keep saving the ones I need, because even the archive eventually deleted, e.g. Objective-C++ docs.
The particularly sad cases are when The Great API Renaming took things with older names that had good documentation and failed to copy the documentation to the new ones! Deprecations usually don’t indicate their preferred replacements either. As has been the case for years, docs may exist if you know where to look.
As for SwiftUI (documentation aside) it is very powerful, even with its current API holes, and the benefits are huge. You do have to slightly rethink how you might approach certain things but ultimately SwiftUI produces shorter and cleaner code with no XIBs. (Hint: If you do end up with pages of hacky work-around code, you’re doing it wrong and should stop.) I have no doubt it will be the primary/preferred mechanism in 1-2 years.
It's such a shame, the original Macintosh programmer manuals (from 30 years ago) - where superb. I can't remember the exact name so can't find them on the internet but they were Multi Volume A4/US Letter size, beautifully typeset and full of information.
Reading this post and I'm feeling incredibly lucky being a Qt/QML developer. Qt documentation is _very_ good. It covers most of questions you might have. And if you encounter some edge cases or obscure APIs, Qt Forum is very helpful with lots of Qt veterans there.
As someone who used to do a lot of Qt and iOS development work it was always very apparent that people cared about the docs at Qt way more than Apple. There was definite areas that weren't quite as well covered, but overall the consistency was very high.
They seem to understand that if it's not well explained it's no going to be used, and then your project is going to die off.
If developers invest a lot of time in getting to know the product, chance is they will be more dedicated to it, so that they don't feel they lost so much time. This is another predatory tactic of this company.
Every June we hear dozens of statements like "We're so excited to see what you do with X. It's so new and amazing." And yet, they barely lift a finger to help developers understand how to use X properly. SwiftUI is a perfect example.
Their developer forums are apparently a place to talk to yourself.
Something is deeply wrong with them and I can't tell if it is merely a case of extreme oblivious arrogance, or if they are self sabotaging, perhaps unconsciously.
The bullet points ("Is the documentation team not given the time..." etc.) apply to a lot of tech companies. "politics or in-fighting" and "not considered a prerequisite for shipping" hit especially close to home.
Not that it's an excuse for anything Apple does, but technical docs are an afterthought at all levels across the board at software companies, and the few places that do them well stand out much more than the many that botch them.
IME that's really the one, at none of my jobs have releases been really urgent, but writing or updating documentation was never really part of any sort of process. To the extent that it existed it was something you'd task one or two persons once in a while, but one or two not-professional-writers can't document the production of dozens of devs and do their own dev.
Producing documentation is looking down upon, it's not factored in any development, it's not part of any development process, and it's not part of any training. Most people also don't enjoy writing documentation, though I couldn't say whether it's because they simply have no training / encouragement for it, or genuine primal dislike.
I've been cursing the same problem with Objective C APIs for audio and some other stuff until I made a discovery: there's quite detailed documentation in comments in the API header files. Apple could generate documentation website from those comments if they wanted, but it seems that they don't want. Overview documentation would be nice, too, because the comments mostly cover details.
> No matter what, I’ve been banging on this drum for years. I haven’t a clue what the problem is at Apple.
The problem is that they are selling a lot of iPhones despite the quality of the documentation.
If bad documentation would translate into no apps and into low sales then they would write top notch documentation. They made such a huge profit instead, no wonder they don't care about this and other issues.
Honestly, reading the headers is the only way to understand iOS, macOS, and iPadOS properly.
I find that the older I get, the more _code is my documentation._ Particularly for things like Python's matplotlib, once you do more than put lines or scatter plots together, you _have_ to understand how the code actually works.
Of course, that's difficult when all you get is header files, but still...
"Code is the documentation" has to have boundaries though, or else you'd have to understand the entire system down to the instruction set in order to print hello world.
Within a small/medium codebase, code is documentation is mostly okay, but for libraries and abstractions you really ought to have solid API docs.
I get the mindset and am very much a read-the-code person as well but my go-to example for this kind of thinking is that reading the code in lieu of a written summary/guide, etc is like trying to understand a book where the chapters and paragraphs are mixed around. It's possible and the ability to do so worthy of pride but it's clear that a succinct summary in one place would be far easier and time-efficient.
Not to say that heavy documentation like this is perfect of course. It just seems like the complexity of the read-the-code solution is sometimes glossed over.
Right, that’s the thing isn’t it—sometimes an abundance of documentation is actually not a good thing. matplotlib is a good example, its documentation fails to convey the common arguments and to what degree they are universal or not; reading the code is really the easier way in the end.
"Poor" implies that it exists at all. For sys admins, most MacOS components are completely undocumented, or are documented with sparse copies of BSD documents from 20+ years ago.
A middling language with exceptional documentation can sometimes be more effective than an exceptional language with spotty documentation. The friction of acquiring sufficient context to get up and running with a language is a huge part of any technical task IMO.
That's just lazy. Apple, a trillion-dollar corporation, has no excuse here. Good documentation is just a function of (relatively small) monetary investment. Invest in tech writers and you'll get great documentation - that's all it takes.
Microsoft's documentation is by and large far superior. My old boss used to say that Apple wasn't a developer company and I would scoff but I think it's true when you compare them to Microsoft.
descriptively: Apple has enough market clout so that it (implicitly) thinks developers will pay the time cost to overcome the lack of documentation and save apple the time it would take to write the documentation. The lever isn't good/bad docs, it's the market dominance apple has in controlling access to high-spend customers.
Similarly, MS was notoriously hard to dev on during MS's period of market dominance. It's a lot more dev-friendly now because it doesn't dominate as much anymore.
I could have sworn I read a comment on this site a few years ago where someone claimed they had to submit a support ticket in order to grt documentation for some Apple API.
Documentation? Apple doesn't have any tools to create it.
Sorry, there isn't a single good tool for documentation, regardless of language, platform or project, in existence, today.
It's frankly easier to point out what non-trash tools for rational human beings we do have, rather than don't have, because it isn't too long of a list.
Apple is CONSISTENTLY underspecifying APIs. The docs never refer back to comprehensive guides. They don't tell me the API constraints. They don't tell me the performance implications.
You may "think" Apple documentation is good, but honestly, it's bad and anyone that also programs for other platforms would arrive at the same conclusion.
I worked at a phone company that was collapsing in market share and one of the things that always stuck out to me was: complex signing process + documentation.
It seems that as you get larger in the phone space, these things are neglected until you lose market share and then they become a priority.
Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me.
So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medium posts because something from before WWDC 2020 might no longer be useful. Or maybe it is. How do you know if the feature changed significantly in the more recent release? I don’t know, but I can tell you where you won’t find out: the official docs.