On Apple's Piss-Poor Documentation | Hacker News Reader

On Apple's Piss-Poor Documentation

caseyliss.com

1,180 pointsingve335 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.

https://developer.apple.com/tutorials/swiftui/

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.

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:

http://web.archive.org/web/20060626083819/http://www.php.net...

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.

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

           ContentView()
              .previewDevice(PreviewDevice(rawValue: "iPhone XS Max"))
              .previewDisplayName("iPhone XS Max")
        }
     }
  }

It turns out what you need to do is pass the PreviewDevice instance into a previewDevice modifier that you've applied to your view inside a struct adhering to the PreviewProvider protocol. I don't think this docs page even mentions that the previewDevice modifier exists, let alone how to put any of these pieces together to configure and display a preview.

You can find how to do this in tutorials elsewhere on Apple's site. But you can't find it in their documentation for Previews, because it's a bunch of automatically generated pages of function signatures with no explanation.

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

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.

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:

https://apps.apple.com/us/app/a-companion-for-swiftui/id1485...

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.

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

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.

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

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.

https://www.relay.fm/radar/204

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.

https://developer.apple.com/documentation/swiftui/progressvi...

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:

https://developer.apple.com/forums/thread/663858

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.

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.

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

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.

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.

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.

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.

https://www.nytimes.com/interactive/2019/09/09/technology/ap...

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.

The difference between https://developer.apple.com/documentation/photokit/phphotoli... and its replacement https://developer.apple.com/documentation/photokit/phphotoli... is pretty damning.

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.

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?

https://developers.google.com/tech-writing

> 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

https://www.postgresql.org/files/documentation/pdf/13/postgr...

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.

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.

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.

Look at the Elixir and Phoenix Framework if you want to see how documentation should be done.

Guides and introduction : https://elixir-lang.org/getting-started/introduction.html

Elixir reference doc: https://hexdocs.pm/elixir/Map.html

Phoenix reference doc: https://hexdocs.pm/phoenix/Phoenix.Controller.html

Big +1. Those docs are a big reason I found Phoenix to be so fun -- all my beginner questions were stupid easy to answer, and my more intermediate questions had guides and links to further study in the official docs.

An example of this that I noticed just recently:

Here's the doc for a deprecated `launch` method of `Process`: https://developer.apple.com/documentation/foundation/process....

It's deprecated, and there's no note on what the replacement should be. Xcode, however, has a hint to use the `run` method. This isn't documented anywhere. If I don't use Xcode, I wouldn't know about this replacement.

And here's the replacement document for `run`: https://developer.apple.com/documentation/foundation/process....

"No overview available".

This is beyond embarrassing.

People speak about Apple excellent libraries, but a lot of these just lack in documentation.

Moreover, Apple will also _remove_ documentation of API they are not favouring.

And it makes sense, Apple is such a monopoly it can afford to have zero documentation, application developer would still need to get users where they are.

But honestly, it's probably more that it's expensive to have good docs, so this job is being optimized out.

Apple no longer gives a shit about developers because they don't have to. They ship as many IOS devices as the China factories can produce and dump trucks full of money keep lining up outside the front door. Why should they spend money on technical documentation, or better developer tools, or even the quality of their desktop operating systems? Those things don't make Apple money.

What makes Apple money is building pretty, locked-down computerlike appliances that are completely under Apple's control. I don't think Apple even sees developers as necessary any more, except the ones in their employ.

This isn't an apple thing. Its industry wide. Much of the good documentation that exists is stuff that was written 20+ years ago by actual technical writers and is still being maintained.

AKA the windows API/etc documentation, linux man pages, etc.

The vast majority of modern documentation is worthless autogenerated garbage when it exists. It lacks good examples, meaningful overviews and functional diagrams. In many cases its woefully out of date because someone rejiggered an API and didn't bother to even update the inline documentation.

One of the better examples of recent documentation is the core rust docs/books. Even then because the rapid release cycles no one publishes an updated "Learn Rust" book for every release, complete with boxes explaining what has changed since the last release. And god help you if you dig to far into the library ecosystem.

I think this is caused by one single problem. Documentation isn't sexy and no one is paying technical writers to do the grunt work anymore. Opensource is a large part of this problem, but the commercial guys have discovered they can save a few hundred thousand a year by simply not having a documentation team, and it doesn't appear to affect them much. A couple youtube tutorials and they are done.

You can see this in the evolution of software, etc. In the 1970's you got large paper manuals which covered every technical aspect of the machine/software. The users were expected to use their brains. Then in the 1980's it all transitioned to "user documentation" which was more focused on manuals that explain how to use the product, by removing the how it works part. Then in the 1990's it started moving to digital copies on disk, and the product came with a 3-4 page manual explaining how to bootstrap enough to read the rest of the docs. In the 2000's it all moved online and became more "marketing" than users guides. In the 2010's they stopped even that. Now you get a phone/software/computer your lucky to even get a piece of paper that tells you how to turn it on, charge it, or install it. Even ms doesn't publish a complete guide to all the magic swipes and keystrokes that are supported by their new shell.

Did you ever look at the Windows API documentation?

Yes, and I know the complaints.

Lets look at https://docs.microsoft.com/en-us/windows/win32/api/synchapi/...

Function description, supported version information, header-file and library file information, meaningful return code documentation, links to an overview of the system wait behaviors, documentation about what happens in low power situations, links to example code using the function, differences in behavior between differing versions, it goes on and on.

Can you point to something you think is better?

PS: I should point out, I have paper copies of the win32 api from the early 1990's that are falling apart from the use they got.

Arr, sorry I misread your comment. I am on your side when it comes to Windows API. But I am not sure if it's a thing of the past. Imo Microsoft is pretty good when it comes to documentation. The way of presentation can be improved, but I really appreciate it. I think it's a culture thing and that culture seems to be different within Apple... I think this is also visible when it comes to their app store policies....

Charles Petzold is immortal!

I looked at the example the article links to, and it's worse than it portrays. Not only is there no information on the requestAuthorization page, but the enum type used, PHAccessLevel, also contains no documentation! Apple, how hard is it to write the different values for an enum?!?

I think this old HN discussion is relevant because it shows that documentation is multifaceted and just one approach doesn't cover everything.

https://news.ycombinator.com/item?id=21289832

I have often seen people complain about auto generated documentation being worse than useless when that is not the case. It's not that the documentation is poor, it's that there is a complete lack of the other 3 kinds of documentation.

Big agree, although I think in this case even the auto-generated stuff being talked about is awful.

I wonder if there is a way to get Apple's attention. There's a lot of power in collective action. It'd be interesting to see what would happen if every developer who was unhappy with the documentation put in an email, a call, or a support ticket.

My other problem with Apple is the lack of PDFs. Apple has a bookstore, I should be able to download the whole of Apple's Developer Documentation on my iPad. I would prefer PDF because I cannot read a screen for hours.

Plus, the examples are almost always broken and don't compile. Broken samples and videos are horrible ways to teach anything.

They used to have PDFs linked from the documentation pages. Obviously that went away at some point.

I don't think Steve would have allowed this to happen. Developers are way too important part of the whole "where the money comes from?" question. He would have noticed the complaints before anyone wrote a blog about it.

iOS docs were great back in 2011.

Docs for the 68k Mac were abysmal. There was a collection of books entitled "Inside Macintosh" that were nearly impenetrable, and only scratched the surface of the elaborate class libraries. Instructions for creating "Hello World" on the Mac were dozens of pages long.

From what I've read, Jobs certainly understood the importance of software, but only great software. He didn't want the Apple ecosystem to become loaded up with crapware like on the IBM, or on the Apple ][ for that matter. So, if a small time developer couldn't write and distribute a crude but useful app, so be it. Favored developers probably didn't fare any better with the documentation, but help was a phone call away.

This was the "closed box" philosophy that I don't think has changed much over the years.

The irony was that "crappy but open" attracted more developers than "wonderful but closed." This is why apps such as assemblers for microcontrollers were written for MS-DOS. Essentially, even after the introduction of MS Windows, the ability to write for DOS provided a way to create and share simple apps.

I still have my copies of Inside Macintosh, I consider them to be examples of good documentation.

They didn't cover "class libraries". I don't have copies of whatever documentation was provided with MacApp, I do have a Think-C manual that describes their environment.

Thanks. I appreciate the counterpoint. I don't remember when class libraries became part of the Mac programming experience, but like you say it might not have been with the original docs.

I agree with this completely.

Apple recently required that anyone using 3rd party authentication (google, fb, etc) in their iOS app, must also provide support for Apple ID signin. That is not an unreasonable request. I was able to implement the signin without too much difficulty. However, when it came to doing a server-side validation of the signin via the Apple API; it was an absolute POS blackbox.

Their documentation and server responses provided no indication of why the validation failed. I searched the docs and forums; it was clear that a ton of other people had the same problem with absolutely no clues into resolving the issue. So I just gave up on it. Total waste of time.

Good documentation is one of those things whose presence is felt only when it’s absent

"When you do things right, people won't be sure you've done anything at all."

Have you considered using Qt? It compiles and runs native on macOS, the documentation is superb. You just let the Qt people worry about the Cocoa, Quartz etc. interface.

As a bonus, it will also run on Windows, Linux, Android, iOS.

Qt looks like an "operating system". It isn't really an O/S, it feeds off the underlying O/S, but to the applications programmer, it completely subsumes the O/S.

We converted a 500KLOC Win32 app to Qt (and macOS), and there is not one single Win32 API call left, except for an obscure font enumeration thing because we wanted to stay with our own PDF code instead of using Qt's.

Qt is not true Cocoa, even still - IIRC (and I think it was literally somewhere on this forum that I was corrected by a Qt engineer) they use the Cocoa things to handle some drawing code, but it's still their own stuff on top of that (they used to use HITheme & co before they modernized it).

It's why you'll see subtle differences on things like buttons.

I can always tell when I'm using a Qt app on my mac, because my keyboard navigation shortcuts don't work

Thanks for mentioning that, I'll try and make sure we accommodate keyboard navigation shortcuts.

The author is a podcaster and developer pretty much focused on Apple and mostly iOS. I think developing for other platforms is a total non issue for him and he also hates C++. I doubt Qt would be an option.

Say what you want about the npm ecosystem, but I've found that the most popular libraries to solve a particular problem are almost always the ones with the best documentation. It's natural selection: the ones that are easier to install/use get installed/used more often.

It's to the point where I expect good documentation, and will pretty quickly discard a library if the docs don't look robust on first inspection.

It's sort of bizarre to me that Apple doesn't know this, or at least hasn't acted on it.

I think they know it's bad, they just don't need to make it better because its their OS so they're the only game in town. Developer experience isn't why people write apps for mac/iOS, so there's not much incentive for them to invest in it.

Apple seems like they are willing to double down on SwiftUI/UiKit with Catalyst.

It's getting less simple for new APIs/features but at least Apple's docs have straightforward hierarchy, even with two separate languages. Duplicate APIs usually get deprecated, like the old ALAssets photo library API.

Try building an app in .NET. There are dozens of different breadcrumbs you can follow on the MS docs for varying versions of .NET, Windows, and frameworks with radically different feature parity and UI systems. Virtually everything you google when building a .NET app has to suffixed with a bunch of identifying information for which libraries and versions you are targeting.

Open source has a serious advantage in this regard because communities tend to congregate around project and documentation styles that are consistent with similar projects, so you already have an intuition for how to navigate a new repo. I find React Native documentation especially easy to parse, although sometimes missing features or examples.

OSs have it tough because their docs aren't tailored specifically to each framework and domain space. But maybe they should be. I think if engineers felt more like they owned their product's documentation, layout, and structure like at smaller companies, they'd be more inclined to make it just right. The SwiftUI specific tutorials are great.

For me, a large part of React Native's appeal is the docs giving me a clear path to make stuff and a fairly public development process. Sure it is also an extra layer of trouble, but I prefer the trouble I can engage with (RN) over the risk of being stranded in the unknowable (Apple).

True, and I do like this a lot. There's a great ecosystem, and the examples are usually pretty good.

But it's also just as easy to get stranded with missing features or features that aren't on both Android and iOS. I did a bunch of geolocation and mapping a while back and I had to write my own support for things like heatmaps. This was eventually merged into the react native maps library, but it is something that can happen if you're doing anything slightly exotic.

Is it really an asset to not have documentation for old frameworks or versions? Some people have customers on old hardware and legacy code using old APIs that they might need to integrate with, it's useful to be able to find out how that stuff behaves.

That's the thing, it's all still there, but it's abundantly clear based on the pages and the list of supported OSs/platforms whether you can use it, and what the new API is.

https://developer.apple.com/documentation/assetslibrary

You need documentation not just to get your happy case working (how do I call this?), but to know things like:

1. Know whether a good behavior you're getting is a fluke, or required.

2. If something stops working with a new release of the API middleware, is it due to their bug, or because you misused it?

3. What limitations of the API will leak through to your program? What input ranges to watch out for?

4. What unexpected situations could occur that must be handled? These won't happen if you get the happy case working, or not all of them.

Even the videos at the latest WWDC have been really challenging. For example, the videos showing new Document Driven apps in SwiftUI never released their sample code as a lot of developers sought here: https://developer.apple.com/forums/thread/651193. They really just presented a glorified demo and a few slides.

And yet the old approach for Document Driven Apps is completely out of date straight from the banner page here: https://developer.apple.com/document-based-apps/ (https://developer.apple.com/library/archive/samplecode/Shape...). As mentioned in a lot of comments, there's a real desire to build apps natively but held back by bugs and the lack of entry through even sample code.

Disclaimer: I work in Developer Relations at Google.

At most large tech companies (Google, Microsoft, etc) the documentation is the responsibility of the Developer Relations team.

Apple has always been an outlier: they never had a Developer Relations team at all. I've recently seen some job postings for DevRel @ Apple, but this is super new.

> Apple has always been an outlier: they never had a Developer Relations team at all.

Not sure if that is accurate, I just did a quick search for “Apple Developer Relations” on LinkedIn and found a bunch of people who’ve been in Developer Relations or Worldwide Developer Relations at Apple for 5 or 10 years or even longer.

I've been working on a very simple (but extremely useful) WatchOS project I'd like to keep under wraps for the time being, as I think it could certainly sell.

Apple's WatchOS documentation, however; is sparse at best, barely there at worst. It's been a problem with various Apple documentation for years.

Out of curiosity, are you talking about WatchKit or SwiftUI?

I also have to agree, now most modern stuff is only mentioned at WWDC, while the older material is only available in the archive, with its replacement being just the "header" file/module listing.

I just keep saving the ones I need, because even the archive eventually deleted, e.g. Objective-C++ docs.

The particularly sad cases are when The Great API Renaming took things with older names that had good documentation and failed to copy the documentation to the new ones! Deprecations usually don’t indicate their preferred replacements either. As has been the case for years, docs may exist if you know where to look.

As for SwiftUI (documentation aside) it is very powerful, even with its current API holes, and the benefits are huge. You do have to slightly rethink how you might approach certain things but ultimately SwiftUI produces shorter and cleaner code with no XIBs. (Hint: If you do end up with pages of hacky work-around code, you’re doing it wrong and should stop.) I have no doubt it will be the primary/preferred mechanism in 1-2 years.

O how the mighty have fallen!

If you haven't ever done it, take a browse through the Inside Macintosh Volume I pdf here. https://vintageapple.org/inside_o/

All API documentation should aspire to be this great.

It's such a shame, the original Macintosh programmer manuals (from 30 years ago) - where superb. I can't remember the exact name so can't find them on the internet but they were Multi Volume A4/US Letter size, beautifully typeset and full of information.

Reading this post and I'm feeling incredibly lucky being a Qt/QML developer. Qt documentation is _very_ good. It covers most of questions you might have. And if you encounter some edge cases or obscure APIs, Qt Forum is very helpful with lots of Qt veterans there.

As someone who used to do a lot of Qt and iOS development work it was always very apparent that people cared about the docs at Qt way more than Apple. There was definite areas that weren't quite as well covered, but overall the consistency was very high.

They seem to understand that if it's not well explained it's no going to be used, and then your project is going to die off.

If developers invest a lot of time in getting to know the product, chance is they will be more dedicated to it, so that they don't feel they lost so much time. This is another predatory tactic of this company.

It seems like stuff like this favors experienced developers who have seen enough to guess how things likely work. They can still get stuff done.

It really hurts newcomers, or anyone in a hurry.

Every June we hear dozens of statements like "We're so excited to see what you do with X. It's so new and amazing." And yet, they barely lift a finger to help developers understand how to use X properly. SwiftUI is a perfect example.

Their developer forums are apparently a place to talk to yourself.

Something is deeply wrong with them and I can't tell if it is merely a case of extreme oblivious arrogance, or if they are self sabotaging, perhaps unconsciously.

The bullet points ("Is the documentation team not given the time..." etc.) apply to a lot of tech companies. "politics or in-fighting" and "not considered a prerequisite for shipping" hit especially close to home.

Not that it's an excuse for anything Apple does, but technical docs are an afterthought at all levels across the board at software companies, and the few places that do them well stand out much more than the many that botch them.

> not considered a prerequisite for shipping

IME that's really the one, at none of my jobs have releases been really urgent, but writing or updating documentation was never really part of any sort of process. To the extent that it existed it was something you'd task one or two persons once in a while, but one or two not-professional-writers can't document the production of dozens of devs and do their own dev.

Producing documentation is looking down upon, it's not factored in any development, it's not part of any development process, and it's not part of any training. Most people also don't enjoy writing documentation, though I couldn't say whether it's because they simply have no training / encouragement for it, or genuine primal dislike.

I've been cursing the same problem with Objective C APIs for audio and some other stuff until I made a discovery: there's quite detailed documentation in comments in the API header files. Apple could generate documentation website from those comments if they wanted, but it seems that they don't want. Overview documentation would be nice, too, because the comments mostly cover details.

I've recently went thru reviewing 20+ JS libraries to draw datatables. Pretty much all of them conflate API documentation with how-to documentation.

You really wan't both, but API docs should always be there - you can hack them together. Listing API's in your how to's is hard to find.

My favourite API docs are pptr.dev and playwright.dev (key being fuzzy search) - do anyone know what tool they use to generate it?

> No matter what, I’ve been banging on this drum for years. I haven’t a clue what the problem is at Apple.

The problem is that they are selling a lot of iPhones despite the quality of the documentation.

If bad documentation would translate into no apps and into low sales then they would write top notch documentation. They made such a huge profit instead, no wonder they don't care about this and other issues.

Honestly, reading the headers is the only way to understand iOS, macOS, and iPadOS properly.

I find that the older I get, the more _code is my documentation._ Particularly for things like Python's matplotlib, once you do more than put lines or scatter plots together, you _have_ to understand how the code actually works.

Of course, that's difficult when all you get is header files, but still...

"Code is the documentation" has to have boundaries though, or else you'd have to understand the entire system down to the instruction set in order to print hello world.

Within a small/medium codebase, code is documentation is mostly okay, but for libraries and abstractions you really ought to have solid API docs.

I get the mindset and am very much a read-the-code person as well but my go-to example for this kind of thinking is that reading the code in lieu of a written summary/guide, etc is like trying to understand a book where the chapters and paragraphs are mixed around. It's possible and the ability to do so worthy of pride but it's clear that a succinct summary in one place would be far easier and time-efficient.

Not to say that heavy documentation like this is perfect of course. It just seems like the complexity of the read-the-code solution is sometimes glossed over.

Right, that’s the thing isn’t it—sometimes an abundance of documentation is actually not a good thing. matplotlib is a good example, its documentation fails to convey the common arguments and to what degree they are universal or not; reading the code is really the easier way in the end.

OMG, their docs for certificates and profiles doesn’t match error messages or xcode or their dev site where you manage them.

I'd like to point out this phenomenon is not limited to their APIs. The docs for sys admins are poor as well.

"Poor" implies that it exists at all. For sys admins, most MacOS components are completely undocumented, or are documented with sparse copies of BSD documents from 20+ years ago.

A middling language with exceptional documentation can sometimes be more effective than an exceptional language with spotty documentation. The friction of acquiring sufficient context to get up and running with a language is a huge part of any technical task IMO.

That's just lazy. Apple, a trillion-dollar corporation, has no excuse here. Good documentation is just a function of (relatively small) monetary investment. Invest in tech writers and you'll get great documentation - that's all it takes.

Microsoft's documentation is by and large far superior. My old boss used to say that Apple wasn't a developer company and I would scoff but I think it's true when you compare them to Microsoft.

descriptively: Apple has enough market clout so that it (implicitly) thinks developers will pay the time cost to overcome the lack of documentation and save apple the time it would take to write the documentation. The lever isn't good/bad docs, it's the market dominance apple has in controlling access to high-spend customers.

Similarly, MS was notoriously hard to dev on during MS's period of market dominance. It's a lot more dev-friendly now because it doesn't dominate as much anymore.

I could have sworn I read a comment on this site a few years ago where someone claimed they had to submit a support ticket in order to grt documentation for some Apple API.

True. But the worst thing is that they do not offer a PR system for contributor to enrich their doc like others one

Apple should print it all up on newsprint and fold it into paper covers, sort of like an old-fashioned phone book.

At least Combine is fairly easy to work with since its ideas are already familiar and Rx was so well documented.

Documentation? Apple doesn't have any tools to create it.

Sorry, there isn't a single good tool for documentation, regardless of language, platform or project, in existence, today.

It's frankly easier to point out what non-trash tools for rational human beings we do have, rather than don't have, because it isn't too long of a list.

Apple can get away with it because the devs are willing to put up with it.

They really should hire the team behind MDN.

How about AWS documentation?

AWS's horrible documentation and user experience is the primary reason I prefer using Google Cloud Platform instead. :-)

From my interaction with GCP docs I think it's way behind both AWS and Azure :shrug:

Documentation doesn't get you a promotion

I disagree with him on header docs.

Header docs are more likely to be kept in sync with the API than whatever they have online.

I always find Apple docs to be good and with right level of information. I do not agree with that article.

https://developer.apple.com/documentation/metal/mtldevice/14...

Here's Apple's documentation on creating a gpu command queue.

https://docs.microsoft.com/en-us/windows/win32/api/d3d12/nf-...

Here's msft d3d12

https://www.khronos.org/registry/vulkan/specs/1.2-extensions...

Vulkan for good measure.

Apple is CONSISTENTLY underspecifying APIs. The docs never refer back to comprehensive guides. They don't tell me the API constraints. They don't tell me the performance implications.

You may "think" Apple documentation is good, but honestly, it's bad and anyone that also programs for other platforms would arrive at the same conclusion.

Not only that - it took me 2 weeks to sell a fucking fone because of the walled garden they..... um.... harvest

I worked at a phone company that was collapsing in market share and one of the things that always stuck out to me was: complex signing process + documentation.

It seems that as you get larger in the phone space, these things are neglected until you lose market share and then they become a priority.

Apple’s signing processes have only gotten less complex from a developer point of view.

But.. this article is completely correct about SwiftUI documentation.

Reply on news.ycombinator.com