Hacker News new | past | comments | ask | show | jobs | submit login
On Apple's Piss-Poor Documentation (caseyliss.com)
1180 points by ingve on Nov 10, 2020 | hide | past | favorite | 335 comments

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. PHP is a horrible language, but I don't hate working in it. The documentation is the reason.

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.

is the PHP standard library still an inconsistent mess?

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:


Agreed -- and the examples in the user comments were invaluable to me way back when I was getting started.

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.

Example programs would be nice too.

Many of them do come with sample code, but like the content of the sessions themselves, they age out very quickly.

Yeah but on the other hand, I'm sure they look at the vibrant 3rd party tutorial content pipeline as evidence that they're doing the right thing.

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.

Try out https://asciiwwdc.com next time you need this.

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.

Unfortunately there's bits of information that are important and only ever appear in the WWDC videos.

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.

You mean you can't figure things out from "public Session getSession(String, String, String, String, String)"?

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.

On the SwiftUI side, you might go digging in these docs for Previews, which are one of its biggest selling points: https://developer.apple.com/documentation/swiftui/previews

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 {
              .previewDevice(PreviewDevice(rawValue: "iPhone SE"))
              .previewDisplayName("iPhone SE")

              .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.

found something! kinda: https://developer.apple.com/documentation/swiftui/previewpro...

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.

https://docs.oracle.com/javase/8/docs/api/java/time/Clock.ht... is a bit more involved than the autogenerated template. The Oracle documentation tends towards this level -- the javadoc template is simply where the docs are kept.

Rust and rustdoc (forget what it‘s called) have the same issues, sadly.

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).

Agreed. Great content. Of course, there is no excuse for Apple's chronic underinvestment in Documentation.

> 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.

Already a thing:


No affiliation. It's sad and a bit pathetic that trillion dollar company can't hire even one person to work on public documentation.

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.

It’s because engineers don’t want to write documentation, and if you don’t force it this is the result.

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.

Just hire Microsoft's people. Not even joking.


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.

[1] https://docs.microsoft.com/en-us/windows/win32/winsock/windo... [2] https://docs.microsoft.com/en-us/aspnet/core/fundamentals/ro...

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...)

There's an old saying at Microsoft: developers, developers, developers, developers, developers, developers, developers, developers

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.

Apple used to be better about developers, I think, back 2000-2010 or so.

Mocked at the time, but looking back it sounds pretty good. Maybe Apple needs a Steve Ballmer.

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.

This. Developers aren't getting credited or promoted for writing documentation, or assisting in the process.

You have to give them time to write it, too.

wrong! bad engineers don’t want to write documentation

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.

>Get ready for documentation subscriptions. I wish I were joking

I thought that was what the $99/year was for.

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 would make sense if documentation were a standalone product, but it's completely complementary to the language, so that doesn't make any sense.

> Get ready for documentation subscriptions.

MSDN Library. Everything old is new again.

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.

> The MSDN documentation has always been freely available

No, it hasn't. It was originally available exclusively to subscribers, and only on CD. MSDN started before the web existed.

Eventually, the documentation became free on the web.

> 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.

What's unfair? It's an accurate actual description with no value judgement.

You seem to be arguing against a negative value judgement which I did not make, or even suggest.

Perhaps, but they didn't charge $3 for the CD, which is about the incremental cost of making a copy and mailing it out would be.

SwiftUI's docs are a nightmare.

Here's a pretty damn cool app: https://swiftui-lab.com

Excellent, thanks for this!

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.

Props to Apple on this one, TextEditor has a real docs page. But it's only for plain text, sadly: https://developer.apple.com/documentation/swiftui/texteditor

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.

Yeah, the sizing thing is a bit of a pain as the creates visible content fitting artefacts when contained in a list or stack.

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.

Many developers are paying for the ability to develop, not the development experience.

Since developers are no longer geeks building "cool stuff in garages", but people who "make flappy bird" - you're not getting away from that $99.

Microsoft: Developers! Developers! Developers!

Apple: Fuck off Developers!

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.

Your work is deeply appreciated

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.

Probably because it’s a competitive advantage for Apple to keep to themselves.

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.

It needs to have more conceptual articles with code listings like this https://developer.apple.com/documentation/swiftui/managing-m....

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.

For example, Previews are one of SwiftUI’s major features. Here’s its docs page: https://developer.apple.com/documentation/swiftui/previews

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.

Turns out this is a SwiftUI modifier that you chain off of your view inside the struct that adheres to the PreviewProvider protocol. See example here: https://www.hackingwithswift.com/quick-start/swiftui/how-to-...

Could you construct that example from having read the documentation? I doubt it.

I built a SwiftApp a few years ago. I absolutely loved working with Swift, but I could not stand the documentation.

Apple was so happy to push breaking changes (without good documentation), that it made it very difficult to work with.

> “Here’s the type signature, have fun!”

My experience with Go libraries in a nutshell. One of the factors that made me abandon that language for others that for me are much more productive.

Yeah, I've found that quite often in apps/libs written for K8s in Go - wasn't sure if it was a Go cultural thing or a K8s cultural thing.

If you're lucky you're getting an example or two in the README.md. The rest of the time, you're reading code to figure out the intricacies.

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.

And on a related note, I just put on yesterday's Under the Radar podcast episode, and their main topic is complaining about this same stuff.


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.

> and always looking at dates on Medium posts

While I'm not an iOS dev I have seen a trend where people have stopped putting in dates of their coding tutorials.

They have an `API Changes: Hide/Show` thing on their documentation (on the right, top) that I think is new fwiw.


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".

How does it compare to Unreal's, I wonder. Seems to have the same problem, third party (Video, bleugh) tutorials.

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 there is a good way to measure documentation quality"

I would start with a checklist:

- is it complete and consistent

- is there a description to every important piece

- working examples

... and if this is complete, you can measure all you want, but I would start with the basics.

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.

Sure there are. I get one every day from my alarm clock 5 minutes before it starts yelling at me.

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.

The other day someone referenced this post by an Apple engineer:


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.

I would struggle to get many things done if not for that one particular Apple engineer and their forum posts.

We all would. Eskimo is a treasure and I have no idea how he does what he does.

Current situation is, money is coming in. Stock market still loves apple. So for them it seems fine.

Basically. What are you going to do? Not release your app on apple devices? No, you will do whatever it takes to work it out yourself.

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.

> the problem is always quality

But writing quality apps requires quality API documentation. I don't know how developers fumbling around in the dark can result in quality apps.

Being "dedicated" to Apple platforms is not the same as being dedicated to 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.

> The primary being it’s easier to keep the documentation up to date ...

That's NOT a "good" reason in any sense.

That's a terrible reason, which no-one in a team leader or above position should ever sign off on.

We're going to have to agree to disagree on this one. But let me give you all an example.

Wolfram Documentation on Mathematica is excellent in my humble opinion. Here is a function I use very often, convolve.


Notice how the interface is very well described, there are examples on how to use it, but there are no implementation details.

Your reference example includes lots of details, examples of usage including source, explanation of options, etc. :)

That's not an "easier to keep documentation up to date" type of thing ;), but is definitely an example of good documentation.

Unlike the Apple approach mentioned above. :( :( :(

Following that reason, the easiest way to keep the documentation up to date is to not have documentation.

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.

Keeping them up to date is also a challenge.

I call it "concrete galoshes": https://littlegreenviper.com/miscellany/concrete-galoshes/

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.

That is a cool story.

I got my first Mac in '86 (a Mac Plus).

My first copy of Inside Macintosh was the hardcover. I think it was two volumes, back then.

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.

This. Their documentation on CoreAnimation concepts was wonderful [1]. It even has these little appendix sections discussing advanced use-cases.

Sadly, they seem to have stopped writing these at around 2015...

[1] https://developer.apple.com/library/archive/documentation/Co...

Relevant username?

The long form guides are great, but for much of SwiftUI they're even missing the most basic 3-line summary of what a thing is.

I so often need to do a simple thing, find a function that looks about right, and the documentation for it says literally nothing about how to use it.

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.

They have such a strong market presence and so much power, they don't have to care for the moment because developers will come to the platform anyway.

"documentation is a huge cost center"

It's a tiny cost center, in the grand scheme of things. As it is they probably spend less than they spend cleaning the glass at Apple Park.

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!

If you haven’t tried Hopper already, it’ll level up your reversing skills: https://www.hopperapp.com/

I'm curious who maintains the Android docs. Is it all open source? Is any of Apples?

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.

Only if you happen to follow Android team developers on Medium (it used to be G+) and Twitter.

The documentation has lots of outdated stuff that only gets updated across Medium, StackOverflow, bug tracking comments, twitter posts, /r/androiddev.

https://en.wikipedia.org/wiki/Inside_Macintosh Guess these days are over...

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.

Really schizoid from my point of view.

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.

I appreciate that closer perspective - I've never been even moderately involved so I expect I only see the noisy things.

The earlier machines I've worked on always did come across as well designed and at least generally well thought through.

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...

No, but I would staunchly argue that Keynote is better than PowerPoint for making and giving presentations.

Apple cares about presentations, and is lukewarm at best about making documents and running spreadsheets. It shows.

You can do a lot more with powerpoint though the results are pretty unattractive, but that doesn't matter to me.

Keynote still feels like an MVP though the results do look a lot better.

I don't think the presenter tools are any better or worse on either system.

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.

Absolutely! Have you seen this (interactive) article by the New York Times? It's unbelievable.


I found it to be believable.

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?

The point is, as written, it's a hit piece.

> I never liked Ballmer, and really never liked the win APIs

actually WinRT is really good. unfortunatly they are barely widespread and probably are not that much used.

C# api docs: https://docs.microsoft.com/en-us/uwp/api/?view=winrt-19041

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.

Leaving iOS dev for Android Dev was the best choice I ever made. iOS dev was consistently miserable.

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.

This is just so.. amateur. The message this sends to me as a developer is: don't waste your time with this unless you have no choice

Wow, that's a great example. I'm also very frustrated by the pretty html with absolutely no value.

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.

Well, stop writing CRUD apps! That's boring indeed. How about you do some real software?

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.

That's just how progress looks like.

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.


And let me cue in my rant from a few weeks ago on the same topic: https://news.ycombinator.com/item?id=24947919

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?

How are the "was this page helpful?" links working out on web.dev? Are you receiving useful feedback?

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.

Great, I'll definitely start indicating good/bad docs from now on. Thanks for you work!

Great insight, thanks for sharing!

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.

An anecdote I heard from a colleague:

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.

These two should be the same, but see the conflicting description: https://developer.apple.com/documentation/coredata/nsmergepo... (in-memory changes trump) https://developer.apple.com/documentation/coredata/nsmergeby... (external changes trump)

Same here: https://developer.apple.com/documentation/coredata/nsmergepo... (external changes trump) https://developer.apple.com/documentation/coredata/nsmergeby... (in-memory changes trump)

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/

API docs example -https://docs.microsoft.com/en-us/dotnet/api/system.collectio...

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.

[1] https://source.dot.net/#System.Private.CoreLib/ConcurrentQue...

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.

Looks like with Visual Studio installation this should work? - https://docs.microsoft.com/en-us/teamblog/offline-book-refre...

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.

[0] https://www.karltarvas.com/2020/10/25/macos-app-sandboxing-v...

[1] https://www.chromium.org/developers/design-documents/sandbox...

Ah, yes, sandboxing, the technically SPI interface that everyone at Apple uses and large third-party apps are tacitly told to use.

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.

100% agree.

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.

I try to explain to non-PHP devs how they live in a world of darkness and ignorance.

PHP documentation is a major factor in it's long-term record.

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.

PHP's documentation is amazingly well done. It goes above and beyond almost everything else.

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.

You can find some good Mac/ObjC docs in the archive: https://developer.apple.com/library/archive/navigation/

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.

I must be missing something here...

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.

This answer doesn't really work for me.

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.

They spend a lot of money on things like Swift Playgrounds, though. They have a whole developer outreach and training program: https://developer.apple.com/learn/curriculum/

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.

This also also having a good sandbox environment and helpful test data that allows you to rapidly iterate with confidence.

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%.

There is no evidence of them doing that. Pretty much the contrary is happening.

At the very least, there is evidence of Jobs' sentiment early on to prevent 3rd party apps on Apple's platform https://www.cultofmac.com/125180/steve-jobs-was-originally-d...

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)

I had a choice, I decided not to develop any software for the Mac.

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 feel as if Apple has let down the software industry by “going with the times” in general.

A “north star” to lots of designers and engineers from interaction design all the way down to the systems level.

Excellent documentation was part of it. Long game. Best practices. The whole “crafting” DNA seems to have been lost somewhere along the journey.

I think it’s also a function of market driven angst and hence not saying “no” often enough anymore.

There's a huge disconnect between informed consumers and the average Apple product owner.

I read an ancedote from an aspiring SWE that after he saw the Apple product he couldn't afford, he knew he needed it.

People aren't buying because quality reasons, they buy because of various psychology tricks their marketing department is responsible for.

It creates a system where developers are dragged along to support 100% of users.

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.

> In terms of quality of products they still are best in their respective class IMHO.

yeah, like the keyboard of the laptop I'm writing from...

>Security, usability and durability

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.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact