1180 points by ingve 1938 days ago | 335 comments on HN
| Mild positive Editorial · v3.7· 2026-02-28 08:14:50 0
Summary Education Access & Working Conditions Advocates
This technical opinion piece advocates for improved software documentation from Apple, framing inadequate learning resources and tools as a workers' issue affecting developers' ability to perform their jobs effectively. The article engages implicitly with fair working conditions and education access rights by emphasizing developers' need for adequate professional resources, educational materials, and workplace support.
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 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.
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.
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.
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.
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'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)
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/
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)
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.
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.
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!"
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.
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.
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.
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.
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.
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 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 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.
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.
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 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.
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.
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.
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.
> 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?
> 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:
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
The article exercises freedom of expression by publicly and directly criticizing Apple's corporate practices using pointed language and advocacy for change. The author exercises the right to voice dissent on matters of public concern.
FW Ratio: 60%
Observable Facts
The article title and text use strong language ('piss-poor', 'despicable', 'embarrassing') to criticize Apple's documentation practices.
The author directly quotes company resources and contrasts them with alternatives, providing specific documented critique.
The blog platform publishes the full critical text and includes a podcast transcript that also voices developer criticism of Apple.
Inferences
The article exercises freedom of expression by voicing public criticism of a major corporation's practices.
The unrestricted publication platform structurally supports developers' ability to voice workplace frustrations and industry criticism.
The article advocates for developers' right to work under fair conditions by criticizing inadequate documentation and tools. It frames poor documentation as a working condition that directly hampers workers' ability to perform their jobs effectively and productively.
FW Ratio: 60%
Observable Facts
The author states 'the number one thing that makes it harder for me to do my job is documentation' and explicitly frames this as a work condition problem.
Multiple developers in the included podcast transcript describe time wasted troubleshooting instead of productive work, including the phrase 'jumping off this cliff, and it's like good luck'.
The article emphasizes how inadequate tools and resources directly impact developers' ability to work efficiently and complete tasks.
Inferences
The article advocates for improved working tools (documentation) as essential to fair and dignified working conditions.
The emphasis on developers' struggle to perform basic job tasks implies that employers have a responsibility to provide adequate workplace support.
The article extensively advocates for educational resources (documentation) as fundamental to professional development and learning. It frames documentation as an educational right and compares Apple's approach unfavorably to exemplary models.
FW Ratio: 60%
Observable Facts
The article uses the analogy of documentation as an 'owner's manual' for learning APIs, establishing documentation as an educational resource.
The author extensively compares Apple's documentation unfavorably to PHP's model, highlighting that PHP provides 'exceptional documentation' with 'example code snippets' and 'comments' that support learning.
The podcast transcript repeatedly emphasizes the need for 'learning resources', 'example code', 'sample code', 'tutorials', and 'examples' as essential for professional education and understanding.
Inferences
The article frames comprehensive documentation as an educational right that enables professional development and upskilling.
The favorable comparison to PHP's documentation suggests that providing extensive learning resources is a standard corporate responsibility toward workers' education.
The article discusses how inadequate documentation creates unfair working conditions by forcing developers to spend excessive time troubleshooting and learning instead of productive work, reducing the fairness and adequacy of their labor conditions.
FW Ratio: 60%
Observable Facts
The article describes developers spending disproportionate time 'figuring things out' rather than building, stating this wastes developer time and effort.
The podcast transcript reports educators working unpaid overtime: 'not-sleeping for three days trying to frantically update all their stuff'.
Multiple speakers describe friction and difficulty caused by inadequate resources, with phrases like 'you're jumping off this cliff' and 'there's still those rough edges'.
Inferences
The article implies that inadequate documentation reduces the productivity and fairness of developers' working conditions.
The discussion of community educators filling Apple's documentation gaps through unpaid labor suggests inequitable burden-shifting away from the company.
The blog platform shares knowledge and learning commentary, supporting professional education and knowledge development within the developer community.
The personal blog platform provides unrestricted publication of critical commentary without apparent censorship or barriers to speech, structurally supporting Article 19 rights.
Article title and repeated use of strong emotional language: 'piss-poor', 'despicable', 'embarrassing', 'Fuck you, figure it out' to describe documentation.
repetition
The phrase 'No overview available. Fuck you, figure it out.' is repeated multiple times as a refrain to emphasize Apple's dismissiveness.
appeal to authority
Marco Arment and Dave Verwohlt are cited as authoritative voices and experts on SwiftUI and developer experience, lending credibility to the criticism.