A concrete example of what goes wrong with Apple's docs | Hacker News Reader

A concrete example of what goes wrong with Apple's docs

amimetic.co.uk

164 pointsimbnwa124 comments

Glad I’m not alone. I’m a relatively senior developer who’s worked 30+ years on a ton of different systems, and every time I wade into the Apple ecosystem in the last 10 years or so to build a native application for macOS I feel like an idiot since it’s much harder to find what I need to know to accomplish something. I always assumed it was because I wasn’t their target demographic: I don’t do iOS apps, and the things I want to write are often not just a matter of throwing together a bunch of widgets and a data model and calling it good. I guess their terrible documentation isn’t a me problem, but an Apple problem.

Add to that the annoying use of videos: I hate finding out that something I’m interested in is buried in a WWDC video instead of written up. I don’t have time or the desire to watch videos as reference material: please stop.

I have the opposite experience. After a decade of backend work, I had to write an app for Windows, macOS and iOS.

The latest SwiftUI is just the best with modern "reactive" approaches working really well. Good community and documented patterns of how things should be developed, packaged and deployed.

The closest alternative is Electron.

The native Windows development is just terrible with tens different ways and frameworks which were abandoned by Microsoft at one time or another.

For the use case of presenting JSON in a pretty way, SwiftUI is great - let’s call that the happy path. But Flutter is also great at that, and you’d only need one implementation that way.

The problems begin when you are doing less trivial or obvious things on iOS/Mac, like interacting with Bluetooth, or displaying large amounts of data in a list, or forms that scroll like your designer wants them to, or background processing, or…

Currently wading through WinRT, and all things look good compared to the WinRT experience.

Layers of false layers of false layers of false laysers ... until you get to, pointer.

HorribleRunOnNameLandOfNoEnd::ThatGoesForeverOffThePageOnEverySingleFunctionCall::WithMassiveChainsThatCompletelyOverwhelmTheirOwnIDE::AndMakeYouTrailYourVisionAcrossMassiveGulfsOfTimeAndSpace::ToFind( int* ptr )

You grab some command line example off the web that seems kind of simple and get:

ExternalDependencies[7777]:

1: _msvc_bit_utils.hpp

1000: DirectXMath.h (?? it's not a graphics app)

2000: joystickapi.h (?? same. totally confused)

3000: processtopologyapi.h (?? we're doing topology calcs?)

4000: windows.devices.smartcards.0.h (?? not a smartcard app)

5000: xpolymorphic_allocator.h

And in using the IDE for a week or so, I've already found so many bugs I don't know what to do. Functions are perpetually listed broken because of an array upfield slightly wrong. It seems compelled to format my code the absolutely worst way available at any given time. It would be better to simply turn off formatting. And ... their example broke. Inside of a bag maze I had no interest in navigating.

> The native Windows development is just terrible with tens different ways and frameworks which were abandoned by Microsoft at one time or another.

As an observer... I'd recommend you find the oldest book on making Windows apps that still works on modern Windows and use that. If Microsoft hasn't killed it by now, it's probably going to keep working for the next two decades.

> I’m interested in is buried in a WWDC video

Or even worse, in a wwdc video that apple has tried to scrub off the face of the internet (anything older than 2017). I still don't understand why they would do this.

My understanding is that they used media they don’t have the rights to or something like that.

> Apple's documentations [sic] is famously dreadful.

The irony is that Apple's documentation used to be excellent, and if you look in the "Documentation Archive", it still contains a lot useful information, especially for Mac and Objective-C development. https://developer.apple.com/library/archive/navigation/

I taught myself Mac development way back in the day using those very docs, which are now sadly "retired".

In my view, there are several reasons for the severe decline of Apple's docs. First, the yearly OS release schedule, which began in 2012 on the Mac, didn't leave enough time to write documentation. (And it doesn't leave enough time to fix bugs!) Second, the arrival of Swift in 2014 forced Apple to rewrite all of the documentation with dual tracks for Swift and Objective-C. Third, Tim Cook and Craig Federighi just don't give a crap about quality.

> Badly designed, legacy OOP APIs

That sounds like a n00b opinion.

Yeah. The Objc docs for coding Mac and early iOS apps was quite good. I used it extensively.

I weep when I read their older HIG for macOS and then see in the current day how hard they violate so many of the principles and lessons they laid down there.

The "Inside Macintosh" series from 1985 was a masterpiece of documentation. It was a bliss to read.

Check the updated docs for "The Standard File Package" which is the UI for selecting files. Page 3-4 (all page numbers has section number). It has full description of the UI, keyboard shortcuts, data structures and example code. It even includes how to customize the dialog.

There is 69 pages of documentation of just how to select a file!

https://vintageapple.org/inside_r/pdf/Files_1992.pdf

Apple no longer understands that good docs is a competitive advantage. The web has such good docs at developer.mozilla.org that it is a world apart.

> Apple no longer understands that good docs is a competitive advantage.

Apple's competitive advantage is the rock-solid, durable hardware (compared to what's considered "acceptable" in the Windows world) and the lock-in effect of things like the App Store and its customer base, iMessage and Find My.

Apple doesn't need to attract developers any more, and so the documentation gets little love.

> Apple doesn't need to attract developers any more

Maybe not, but I have found that better documentation helps me write better, more reliable software with less time wasted on trial and error and fruitless internet searches.

Me as well, but Apple doesn't need to take care about that.

Well put. Unfortunately true!

Surely they can afford to hire a few good technical writers, right?

Presumably SwiftUI should also be easier to write code for than the classic Mac toolbox?

When I got into iOS development (about a decade ago now) I was absolute blown away by how good Apple's documentation was. It was accessible to someone unfamiliar with their platform, well written, and covered everything from the high level to low level details. Sadly that seems to have also been the exact moment that they fired everyone working on documentation.

> Sadly that seems to have also been the exact moment that they fired everyone working on documentation.

Out of curiosity, when was that?

Case in point, here's the archived documentation on how to use Open and Save Panels, with example code:

https://developer.apple.com/library/archive/documentation/Fi...

(Third link when searching DDG for "NSSavePanel example".)

> First, the yearly OS release schedule, which began in 2012 on the Mac, didn't leave enough time to write documentation.

I'd think this problem could be partly solved with money, i.e. hiring more writers.

Even if the docs had to lag the OS release by a few months, I still suspect the fundamental reason is:

> Third, Tim Cook and Craig Federighi just don't give a crap about quality.

> I'd think this problem could be partly solved with money, i.e. hiring more writers.

That's classic Mythical Man-Month thinking.

Sure that applies to software development, but does it really apply to writing documentation? The articles currently on the developer page could be split up evenly between a team and be worked on simultaneously.

Writing documentation requires communication and collaboration with engineering. As you add people to an organization, you also add meetings, bureaucracy, and various other encumbrances. Not to mention that the technology to be documented needs to be done or done-ish, which is difficult when you're shipping major updates yearly!

Besides, how large do you think the talent pool is of good documentation writers? I would estimate that it's actually harder to find good technical doc writers than it is to find good programmers.

1) The minimum qualifications for a good API doc writer is practical experience programming with the technology to be documented. That already narrows the field significantly. You can't just a hire a comp sci grad straight out of college.

2) Indeed, a comp sci grad straight out college probably wouldn't want the job anyway. A lot of people aspire to be programmers, because it seems cool, fun, and has excellent compensation. Not many people aspire to become doc writers as a career.

3) The compensation for doc writers is generally lower than for programmers, so if you're already an experienced programmer per 1, then why would you take a step down?

4) The natural retort is going to be, "Just pay doc writers more!" But that's not going to work for several reasons. First, the programmers will be unhappy if the doc writers are paid more than them. Second, companies don't value doc writers as much. Third, once you get off the programmer career track and write docs, it can be difficult or impossible to get back on the programmer career track if you ever want or need to leave Apple. In general, the market is not huge or lucrative.

What you tend to get for documentation writers, then, is often older programmers who are starting to experience age discrimination, finding it harder to get a programming job, so they settle for writing API documentation. But that's not a huge pool of available workers.

The way you describe the problem, it sounds like paying them more fixes things and the objections to paying them more are wrong.

And as far as the "career track" aspect goes, have them keep coding part of the time and keep calling them a programmer.

> The way you describe the problem, it sounds like paying them more fixes things and the objections to paying them more are wrong.

It sounds like you have a reading comprehension problem?

> And as far as the "career track" aspect goes, have them keep coding part of the time and keep calling them a programmer.

1) You're missing the part where the majority of programmers don't want to be doc writers, aren't qualified to be doc writers, and aren't good at being doc writers.

2) It's not as simple as having them "keep coding part of the time", because the standards for hiring a coder are different from the standards of hiring a doc writer. Apple wouldn't necessarily hire the same person to do both. It could be a rare situation where Apple would consider the same person to be good enough for both jobs. This is like saying of an American football team, "Why not just have the quarterback play defense part of the time?"

Remember, the point of this is to produce high quality docs. Quality over quantity. Apple is already churning out low quality docs.

What kind of mythical quality is you imagine required to add examples to documentation???

> Apple is already churning out low quality docs.

The article listed some stats where Apple is not churning out enough docs. So there isn't even quantity

> What kind of mythical quality is you imagine required to add examples to documentation???

I can see that you have no respect for the difficulty of writing good documentation.

That's a reading comprehension issue

> It sounds like you have a reading comprehension problem?

Well that's extremely rude.

You listed objections people might have and I'm calling those objections shallow and bad.

> This is like saying of an American football team, "Why not just have the quarterback play defense part of the time?"

This is a situation where you need experience on the defense to be a good quarterback, and physical shape is irrelevant, and the quarterback is worried about permanent salary loss because other teams don't value quarterbacks. In that case it would make sense to have a single job title and have them do a mix so they stay fresh on their defense experience.

Even if the doc writer isn't the optimal programmer, consider the gap as a training expense and a way to make sure you have enough doc writers applying. If it's a bad idea then there is always the option of paying them even more to compensate for career damage.

And nowhere did I suggest making the normal programmers do the doc writing.

Most of the issues you've described have nothing to do with the "mythical man-nonth thinking", so it would indeed be possible to just throw more resources at the problem

And the talent pool at the level of a single company is practically infinite unless you indeed introduce artificial constraints like not wanting to pay to tap into that wide pool

> Most of the issues you've described have nothing to do with the "mythical man-nonth thinking"

Hence the "Besides..."

> And the talent pool at the level of a single company is practically infinite unless you indeed introduce artificial constraints like not wanting to pay to tap into that wide pool

I just explained how that's untrue, and it feels like you completely ignored what I said.

You can't just say that Apple is "a single company" like any other company. Apple is the largest platform vendor in the world. How many other single companies have platforms like iOS, macOS, watchOS, tvOS, and now VisionOS? How many other single companies have effectively two bespoke programming languages, Swift and Objective-C, much less one? Perhaps only Google and Microsoft are comparable in their massive need for platform docs.

>You can't just say that Apple is "a single company" like any other company. Apple is the largest platform vendor in the world.

The world is HUUUUGE (even limiting by language), so not only can I say "a single company", I can raise it to the level of "a single tiny company", especially when it comes to such a small scale issue

> How many other single companies have platforms ... bespoke programming languages

How does it matter? There are gazillions of educated people in the world with all the skills for a couple of order of magnitudes more languages than just 2! And it's especially preposterous making this arguments after waves of layoffs in the tech sector

And you can't reject a simple solution "just pay more" with "companies don't value doc writers": that explains why they don't hire enough people/don't care about the quality of their output, not that there are some inherent talent pool limitations

> How does it matter? There are gazillions of educated people in the world with all the skills for a couple of order of magnitudes more languages than just 2! And it's especially preposterous making this arguments after waves of layoffs in the tech sector

I already explained how it matters: "The minimum qualifications for a good API doc writer is practical experience programming with the technology to be documented. That already narrows the field significantly."

You seem to think that it's just a trivial skill: https://news.ycombinator.com/item?id=38914104 But when you look at the Apple documentation archive, and the extensive, excellent conceptual articles, it's clear that this accomplishment required a lot of care, experience, and skill.

You haven't explained it since it doesn't follow. The fact that a single company uses many technologies has no effect in itself on the pool of people using those technologies.

Besides, that's another misapplied requirement of yours: experience can be gained, it will take longer, but it's just another "takes more resources" issue, not something that narrows the field since for some reason you added that requirement before hiring, not before writing docs.

I don't think it's a trivial (that's your straw man), I just disagree that it requires rare man of mythical set of skills to accomplish to make it justifiably hard for poor Apple

> That's classic Mythical Man-Month thinking.

I see why you said that, but I don't think that's the case here.

The tech writers don't necessarily need to collaborate with the developers as the software is being developed.

E.g., the tech writers might be able to look at new APIs, the source for for their implementations, and any in-house code that uses / tests those APIs. And then write documentation based on what they find.

If they're able to talk to the developers during or after the API is released, all the better.

Disclaimer: I'm not a tech writer. I'm just speculating on how this could be made to work.

I don't see how.

That applies to trying to get a specific project done faster, when it's already pretty far along in the development cycle.

The problem of an area not getting enough attention for years is a great opportunity for more workers.

Maybe I’m a bit of an outlier, or maybe personally outdated, but I find Apple’s documentation to be generally good, albeit requiring patience.

Apple’s documentation offers neither examples nor answers to common questions (features of stellar documentation), however it works well with a first principles, read-it-twice mentality. The key info is there, just not emphasized.

For those who read the documentation twice and feel comfortable organizing the architecture without guidance, the documentation is highly workable.

I wonder if folks more grounded in web development favor a quicker, architecture-agnostic, copy/paste, just-work-out-the-box style of documentation. (When I’m working on the web, I do!) But Apple’s platforms are native, their frameworks build upon native infrastructure, and so they require consideration of the fundamentals and underlying systems, features that preclude just-give-me-the-snippet development.

(That’s my take, with my own biases. I don’t mean to contradict or put down any other perspectives. I am certain that in many ways, including many of which I am unaware, I am naive.)

Additionally imho, Apple does a fantastic job in "naming" things, everywhere in their ecosystem - including their SDK

The overly descriptive names get made fun of online, but they’re frequently self-explanatory enough that they can be pulled from autocomplete, skipping the documentation entirely.

Yeah I’m with you. I don’t understand what everyone is complaining about. There’s a few things that are undocumented here and there (IOSurfaceRef) but you can sniff out how it works with a little trial and error.

I often code offline with only the Apple docs as reference, not a problem.

How much trial and error to sniff out 80%?

"Core Audio 124 / 618 (20.1%"

Except that "examples" and "answers to common questions" are at the top of the "first principles" when it comes to documentation, so yeah, if you ignore key quality metrics, quality improves

What do you mean by “first principles”? Do you mean top-ranking criteria? Or do you mean axiomatic?

For Mac desktop programming and Swift in general, I find ChatGPT quite helpful. It’s been quite good at dredging up the kind of “one weird trick” I tend to need to work with these kind of closed source framework that you can’t truly understand. I don’t think I’ll ever get used to Apple stuff since I’m so used to being able to go-to-source of frameworks in Java/Ruby/Android/Go/C/Javascript programming but ChatGPT at least keeps me unstuck.

At least SwiftUI gives you a very nice paved road of productivity. Again if you need something off the beaten path good luck, but it’s never been easier to make app-shaped tools for Apple platforms.

I'm dreaming of the day there would be a chatgpt like thing for all those internal proprietary tools and their "documentation"

What’s the difference you’re imagining from today’s ChatGPT?

ChatGPT knows nothing of those libraries and their code. I can't paste anything into context, because of security reasons :)

Ah I understand now. I have my eye on SourceGraph’s Cody AI, they’re working on an enterprise version, although it’s TBD how locked down it will be: https://sourcegraph.com/cody

My experience as well. While I’d love a proper go to source approach, chatGPT nails most of the issues I run into with SwiftUI.

ChatGPT has been a godsend for helping me figure out how to use quite a few Mac and iOS APIs in the last year. There are APIs that would’ve taken me an hour or more to work out how to use by searching online, experimenting, digging up old WWDC videos (often the only place to really learn how to use a given API properly), but now it takes seconds of ChatGPT. It’s been a game-changer.

100%

I put the query in the top of the page into chatGPT with the same requirements (Mac OS, in swift) and I got back detailed explanations, sample code, and basically all the writer was looking for.

Not great that OpenAI is serving as better docs than apple’s own, but at least there is an alternative.

ChatGPT has been similarly helpful for working with xcb/xlib and teasing out the arcane bits of X11. I don’t know how anybody had the patience to sift through the scattered writings on those things before… maybe I just don’t know where to look but I find it much more challenging to dredge up info for than anything related to Apple platform development.

> I don’t know how anybody had the patience to sift through the scattered writings on those things before.

Foundational knowledge. Before you delve into x11, you learn how graphics works at the lower level first, and then you build upon this. Before the actual implementation, there was a design. Once you figure it out, you can guess how the implementation is done. You confirm your guess from the docs and code if it’s available.

Does Apple have developer relations engineers? Surely they must have some engineers that participate on social media, and they could be asked directly.

It's honestly baffling that we have no mechanism by which to increase accountability within technical domains from these large corporations.

And if you reach out to Apple, you're more than likely to get either radio silence or a canned PR response that doesn't answer anything.

It makes me wish that we had powerful technical figures willing to hold other tech figures accountable in public. Why isn't there anyone capable of setting up an interview with the Apple CTO and questioning them directly on the importance of developer tooling and relations?

They're weird because supposedly their processes and documentation predate many others. It's as if they're gradually becoming the soviet kremlin. Still good at all that secrecy stuff, but the actual processes behind that opaqueness increasingly more stubborn and clunky.

Like a deaf grandpa still being able to do great stuff but not remembering to keep the shop in order or to take notes so you have to ask loudly.

>Does Apple have developer relations engineers

There's a few that participate in the apple developer forums (quinn is the most notable one). There's also DTS tickets which you can file

Every WWDC is a good time to get in touch with them where they host Slack chats.

Great! I only have questions once a year and this is prefect for me!

Apple doesn’t really have a social media policy. Their default go-to is “don’t”.

Not quite dev relations I’ve seen Apple devs talking about what they’ve worked on increasingly frequently on Mastodon.

I'd love to understand WHY Apple's documentation is so notoriously weak.

One guess: maybe it's related to their culture of internal secrecy? If a team works on a project for years without anyone outside of that team having any visibility of it, writing comprehensive documentation is presumably a lot less valuable - at least while it's under development.

It’s gotten worse over the years. The new Swift stuff tends to be cursory, but I frequently hit “archived” legacy docs that are super well written and go in depth on whole systems (although it’s now 10 years out of date). My favorite bit of technical writing is the old text system docs: https://developer.apple.com/library/archive/documentation/Te...

My hypothesis is that in the old days, technical writers on teams would lead the docs effort, but today’s culture may have many teams with only developers, and those developers are primarily interested in shipping code, not docs.

> My hypothesis is that in the old days, technical writers on teams would lead the docs effort, but today’s culture may have many teams with only developers, and those developers are primarily interested in shipping code, not docs.

And writing good documentation involves a fair bit of QA and remediation effort as well - you don't want your consumers to yell at clouds "why is the stuff in the official documentation not working", so the writers should actually go and test stuff themselves to see if the docs are actually still valid.

This is what permanently burned my relations with Openstack - half the stuff in the docs was broken when I tried it, either from old age or never being tested out of Redhat.

In the old days, they needed to convince people to work on Apple-specific APIs. Mac OS X was miniscule (smaller than today), iOS was either new or didn't even exist.

Nowadays, folks have to develop for iOS whether they like it or not, and macOS is on the backburner.

Will absolutely cosign this. So many of Apple's components for both iOS and MacOS development are dreadfully over-complicated and the documentation if anything, makes it worse with no examples provided, no use cases, nothing. And of course is subject to change at the whim's of Apple's engineers.

So often as a developer I end up just creating a single-line static wrapper function that does something that interfaces with Apple code, then call that instead. Things like a share sheet are incredibly complicated for seemingly little if any actual need. Example: I have a static wrapper function for sharing that accepts the following parameters:

- The View Controller to present the share sheet from

- The originating view/button that it should be presented from (on iPad)

- The URL of the file

- A subject and message, either one, both or neither, appropriate to the share

And that's it. Five pieces of information. Inside that function I:

- Load the data from the file into a Data object, and confirm the URL is good

- Save a second copy of the file to the file system with the appropriate name I'd like it to show the user

- Convert the "Any" object passed into the button (view, button, bar button item, etc.) as a set of coordinates from which to spawn the popover, because Apple's code does not do this reliably

- Instantiate a Share Sheet Subject Body Provider, which is an object you have to provide the share sheet which contains... 2 strings

- Instantiate a UIActivityViewController, which is a subclass of View Controller using the subject/body provider and the URL to the file copy I created as the arguments for that

- Set the source view of that controller to an arbitrary View I've placed that's just the coordinates from earlier, with a height and width of 1, placed onto the view controller

- UNLESS it's a bar button item, in which case I set the bar button item property to that and skip the coordinates altogether

- Then I present this view controller on the origin view controller

And I'm sorry, I'm willing to grant that some of this complexity is down to engineering concerns I'm not aware of, or taking into account things I've never done. But holy. Shit. What a process to go through. To simply share a file as Apple intends, I need a class that is fifty lines of code, and a second class of another 20-ish lines, to provide subject and body. Which again, I cannot stress this enough, is TWO. STRINGS.

SURELY. SURELY SOMEHOW we could make this easier.

There's no reason they can't have amazing documentation, but I imagine they don't because people are going to use the platform anyway. People are basically forced to use it because that's where so many of their customers are, so they can just treat their users like crap and get away with it. Why spend time on documentation when it will probably only cost them money to do so?

Such a sad state of affairs.

Your treatment-as-crap is Apple's MAKE-GOB$-OF-CA$H. Need I elucidate ?

It’s a pity when you consider how detailed Inside Macintosh was.

Apple and Android mobile development both have some of the worst APIs and designs I’ve ever seen. I really can’t believe these companies have the most talented developers based on their objective output. I think at best, they have a small handful of incredibly smart devs and the rest may as well be leetcode monkeys.

That's because there's no competition, you are building an app? Then you need both an iOS and an Android version, no matter what. Their docs can be as broken as they want, you still have to target the duopoly.

That’s starting to change now where you have things like Flutter which get you native cross platform apps with excellent documentation https://docs.flutter.dev/

Flutter is a very leaky abstraction

Want to provide some examples?

For example, there's this package to test Internet connectivity (I know just trying is the best solution). Its readme says

> On Android, this does not guarantee connection to Internet. For instance, the app might have wifi access but it might be a VPN or a hotel WiFi with no access.

While I unterstand the technical reasons for this limitation, I don't get why it's different on Android. What happens on iOS or web builds?

Also check out this FAQ which is full of platform internals which I don't want to care about. If I need to know what permission from the library map to which platform-specific permission, it's not doing a very good job at Abstraktion. And yes, it is a very hard problem.

https://pub.dev/packages/permission_handler#faq

I’ve had little issue with Apple stuff (especially iOS/UIKit, which is significantly more polished than macOS/AppKit), but Android? Yeah that’s a mess. Jetpack Compose helps some but it still has a long way to go. If I could use UIKit on Android and forget Android Framework ever existed I would.

I'm dealing with this daily as I build Applin.

Example from Friday: I spend about an hour figuring out why my iOS app was not showing an error response when the server refused an upload. The iOS standard library URLRequest class was not sending the "Expect:100-Continue" HTTP header. I found nothing about this in the docs. I found the answer on Stack Overflow: add the header to the request and the class will automatically use it and wait for the "100 Continue" response before sending the body.

Last week, I spent multiple hours getting UIPickerView to work. The docs omit critical info like how to update the widget. Also, the API design is confusing: one must implement UIPickerViewDataSource but that isn't actually used as the source of the data, only the count of components. To make the picker work, one has to implement UIPickerViewDelegate which provides the actual data. It's a very confusing widget.

Earlier in this project, I wasted multiple weeks struggling, unsuccessfully, to get UITableView and UIStackView to work for my use-case. This took so long because the docs are missing lots of important info.

Shameless plug: Backend engineers can use Applin to build iOS apps, without writing any frontend code and without struggling to understand Apple's poorly-documented buggy APIs. https://www.applin.dev

I went through pretty much the same dance yesterday trying to figure out the right way to choose a directory in my SwiftUI app. SwiftUI is a wonderful UI toolkit but it's far from complete. The documentation Apple is creating for it is wonderful, check out: https://developer.apple.com/tutorials/swiftui

Sorry, this really feels like a user problem. Someone who is used to functional or dynamically-typed languages where one has to read documentation in a browser instead of just navigating around a strongly-typed SDK codebase and understanding how it works from within the IDE.

I have done ZERO development in Apple/iOS/macOS. I have written ZERO lines of Swift or Objective C. My experience is with Java and C#.

But when I opened the first link in the blog that took me to https://developer.apple.com/documentation/appkit/nsopenpanel the very first thing I saw was

class NSOpenPanel : NSSavePanel

And after scrolling through the page, before I even went back to the author's blog I had already clicked on "NSSavePanel", saw what was listed there https://developer.apple.com/documentation/appkit/nssavepanel, and then even further up to https://developer.apple.com/documentation/appkit/nspanel, and so on.

For me, this was absolutely the most natural way to navigate around an unfamiliar SDK/library/codebase. Understand everything that's available on the object from it's inheritance chain.

So when I went back to the blog and eventually came to:

> Ah, it inherits from NSSavePanel! That was not at all obvious (and I'm sorry OOP devotees, that makes damn all sense in principle). Oh, look, loads of new functions and properties. Ah, so I'm meant to query the NSOpenPanel object for the directory.

I was extremely confused.

I'm far from an OOP devotee, but I don't understand how you can attempt to write code in an OO-language without understanding that inheritance is one of the most important concepts for code separation. (and is almost always an anti-pattern, but regardless).

This is all absolutely information I would expect to discover from within my IDE, I wouldn't even go to the browser for it.

I suppose I will have to admit that "Open Panel" inheriting from "Save Panel" is weird - it's definitely a code-reuse paradigm and not a correct use of "isa" inheritance. Except this is literally how it works in every other desktop UI framework I remember using - MFC, Visual Basic, Java Swing. I could be wrong, but I think it's a pretty common convention in desktop UI development.

I agree with you. Everything this person is struggling with is well documented on the parent class. A basic understanding of OOP is all that's needed to use this documentation and this dialog.

Are they mad at Java docs? Or C# docs? Or any other OOP doc that follows the same pattern of not repeating the parent's documention on the subclass unless the subclass adds to it.

The charitable view would be that they come from language/platform that does include the base-class's methods/apis.

Your example of dotnet/C# doesn't seem to be the best - DotNet/C# repeats the base documentation - for example the SaveFileDialog class [1] lists all of the methods but indicates when the methods come from the base class.

Flutter also seems to list inherited methods - for example the TextButton [2].

[1]: https://learn.microsoft.com/en-us/dotnet/api/system.windows....

[2]: https://api.flutter.dev/flutter/material/TextButton-class.ht...

Yeah as someone who does work in the ecosystem but has never used this api or built a mac app I felt the same, the docs assume some familiarity with inheritance and delegation which is still used pretty much everywhere in the ecosystem, so you are gonna need to understand those to get anywhere. I do kind of agree that apple’s docs aren’t great but this is a bad example.

Atomization is one of the unfortunate side effects of the web. What's worse than Apple docs? NVIDIA/Mellanox docs. Use-cases are tucked away in 75 million different URLs, web pages, power-points, .txt docs, stack overflow posts and what not.

I long for time and place where I can download a standalone user-guide, a technical guide, and an API reference as PDFs and rendered as searchable docs.

That NSOpenPanel class reminds me of MFC days. For those young enough to remember, it's Microsoft Foundation Classes, the UI framework for Windows. Everything had to be a class in MFC: new window - a class, file open dialog - a class. In order to understand what you code does, you have to analyze the whole hierarchy of classes, and figure out where that particular virtual method that you need is implemented. Deep inheritance hierarchies of MFC coined the term "fragile base class" problem where changes to a base class can inadvertently affect the behavior of derived classes, potentially causing them to malfunction or behave in unexpected ways.

Every now and then I dust off Xcode to try and build myself some (pretty simple) native macOS app – just for funsies.

For reference I am a backend dev at a SaaS company dealing primarily in Python & Go, doing HTTP/gRPC services and talking to databases.

Last night I attempted to make a program that would display an image and allow the user to click the image and then display the hex value of the colour under the cursor.

I wanted my application to use a crosshair cursor and after an hour of looking at the docs for NSCursor[1] and stackoverflow I just gave up.

I don't know how someone gets started in this ecosystem but I am sure once you know it this stuff is easy.

[1] https://developer.apple.com/documentation/appkit/nscursor

It’s in the page you linked under set(). Combined with the properties at the top of the documentation page, to make the cursor a crosshair you’d call NSCursor.crosshair.set(), after which it’ll remain that cursor until something else changes it (so for instance, you’ll need to call it whenever the cursor enters the relevant view since e.g. crossing window borders will change the cursor).

Thanks for that comment.

That weird "relaxed" notation that Swift brought to Apple's current doc format/structure made it so frustrating if you just want to use a certain thing without capturing the whole framework.

In 2024 you better have some scratch paper at hand to make notes when browsing Apple Swift docs...

It's why I never really bothered with Mac OS or iOS development. I don't have time to waste searching for answers. What an absolute PITA.

I like learning from 3rd party sources, but there HAS to be an official, maintained 1st party source or there is no point.

My fuzzy understanding is that organizationally, the teams / org that was originally responsible for writing good documentation at Apple became the App Store review teams. And thus never again was there time for writing good docs.

> My fuzzy understanding is that organizationally, the teams / org that was originally responsible for writing good documentation at Apple became the App Store review teams.

Not sure where you got that, but I know some people inside Apple, and it sounds totally wrong and baseless.

Meanwhile, here are the Haiku docs for BFilePanel (thanks BeInc for great docs). Who said C++ was hard to use?

https://www.haiku-os.org/legacy-docs/bebook/BFilePanel_Overv...

Recently have the same experience, I was writing a small SwiftUI app for macOS and wanted to detect the hardware keys and handle it, especially the Delete key. It was hard to find it in Apple’s doc. But I figured it out with some random blog and a lot of print() on my end.

The worst part is not only that the documentation is awful but that Apple uses needlessly overcomplicated OOP design on top. It’s just a bad experience all around. I don’t think SwiftUI is any better either, though it avoids the old OOP mess it is still very complicated and if you want to do anything not immediately supplied by the library you often are best falling back to AppKit anyway. It’s just very unpleasant programming in general

SwiftUI started out really simple but now that they're extending it to cover more functionality it's getting more and more complicated. Instead of complicated OOP design now it's inscrutable functional design, now with the bonus of Swift's "less verbose" syntax and naming.

I was dealing with TransferRepresentation the other day and this API must be extremely confusing to someone who's new to Swift. The documentation reads like you're supposed to already be familiar with some concept that is never explained.

I totally agree. The code supporting the “concise” framework is so complicated it’s almost impossible to add any functionality

Off topic: Documentation seems good on Next Step 3.3 and OpenStep 4.2 Developer CD.

Don't forget, one of the things you get for the $99/year developer fee is documentation.

https://developer.apple.com/support/compare-memberships/

Does this mean you get additional documentation then the example in the blog? Or is that $99 for the bad documentation?

No, it's the same documentation.

I think even for the new APIs added in non-public betas, it's all on the main website now.

Also there's docs that aren't on the dev.apple site for things like Apple Pay, but it's not a perk of paying $99 a year. I suspect the actual hardware docs for the Vision headset are private too (they were for the Apple Silicon DTK).

As far as I know, all the docs are free and don’t require logging in to view.

The only hit for the word “documentation” on the linked page is this paragraph which explicitly says you don’t need to pay to learn:

> You can learn how to develop apps for Apple platforms for free without enrolling. With just an Apple ID, you can access Xcode, software downloads, documentation, sample code, forums, and Feedback Assistant, as well as test your apps on devices.

> as well as test your apps on devices.

If only it was simple. I had a paid account and lots of test devices. I let it lapse.

Now I can’t test on my own device with my normal iCloud account as I have too many registered devices for a free account, and I can’t access the interface for deleting those old devices.

This edge case has existed since ‘free’ accounts came into existence.

I hesitate to defend Apple developer documentation. I have struggled with it for 30 some years, but if you don't understand OOP on the mac (inheritance etc.), you probably shouldn't attempt to program the mac.

This reminds me of a UNIX programmer I worked with who called up our Apple sales rep and berated her and Apple because programming macOS wasn't like programing UNIX. When I called her to apologize, she was nearly in tears.

You are way outside this field. Programming the macOS can be very different and difficult. Either learn its concepts or work on something else.

Docs are the place people go to to learn the concepts. Examples is one way how docs teach those concepts.

Launch HN: Hi everyone, I'm politician, and I'm happy to launch a new service called AppleDocs.ai. We use generative AI to make Apple developer documentation useful, since Apple has completely dropped the ball on this area. Pricing starts at $8/mo for individuals.

/satire, but only barely -- upvote if you want this to exist!

The LLM would be a gimmick. If you were to really do this, you'd have to manually test everything anyways before selling it. A decade ago what you described would have been called "a lazy cashgrab".

Given my super limited experience working on the most basic bare bones of iOS apps, I would pay for this.

I've actually been waiting for something similar - basically some kind of LLM-powered auto-reviewer that checks whether the documentation and the code are in sync on commit.

I've seen so much outdated documentation recently that I'm starting to ignore it and go straight to code (+1 for open source I guess).

It might be a hot take, but I think documentation is mostly obsolete. Nobody wants to write it, and nobody wants to read it.

How the future works is probably:

1. Tutorials / case specific guides 2. documentation-annotated code base read by an LLM to yield answers to questions.

Already now, the most popular open source projects seem to prioritise guides for common use cases over extensive documentation.

I'm pretty sure both of those count as documentation.

https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

I think you mean something a bit more specific, maybe "comprehensive reference documentation written by humans", though I'm not sure codebase annotations get away from that.

Yep, you are right. I was not precise enough.

I disagree. Golang and its standard library are terrifically productive for me because they have plain old high quality module documentation on every public struct and function. Of course you need a few tutorials to introduce people to a library’s main use cases but after building that initial familiarity I find the kind of docs Go has to be the most useful for me. A doc browser like Dash (Mac) or Zeal (open source) that makes search lightning fast multiplies the helpfulness of that kind of docs.

Wow, that was indeed a hot take in my original comment. Net 5 downvotes for a comment that is not at all slurs and represent a genuine opinion about the future of software development.

Anyhow, I am concerned about how the new wave of AI tech is going to affect the software development market. A lot of people are focusing on code synthesis. I don't think that is just around the corner. I think think it is going to be in assistive technology, such as learning / helping writing code.

I also think a lot of contemporary programmers are attached to documentation and overly focus on it's value, which indeed was important in an age of that being the only way to disseminate the intended workings of a library.

I can say that already know https://inkeep.com/ is working on this type of tech (The I prefer over reading documentation on bun.sh), Pulumi also have https://www.pulumi.com/ai that I prefer over reading Pulumi's documentation.

Anyhow, the future will show how this works out.

> nobody wants to read [documentation].

OP wants to read documentation. It's in the article.

Quite a few commenters say that they're resorting to LLMs, not because that's how they want to learn about the code they're using, but because the documentation is terrible and LLMs summarising snippets from dozens of different forum questions and blog posts is the only alternative they have to terrible documentation.

> most popular open source projects seem to prioritise guides for common use cases over extensive documentation.

Open source projects that people aren't being paid to work on probably don't have extensive documentation, because writing extensive documentation is hard, and the kinds of people who like hacking on code that solves their problems are probably not people who enjoy writing extensive documentation when they could be implementing another feature. Even if a large segment of their users would prefer that, and it's what would be best for the project.

You beautifully highlight the economics behind why this is the future of documentation:

> the documentation is terrible and LLMs summarising snippets from dozens of different forum questions and blog posts is the only alternative they have to terrible documentation.

and

> aren't being paid to work on probably don't have extensive documentation

This will only get strengthened when people discover that the outputs of LLMs suffice.

I won’t merge any PRs to my open source projects without a corresponding documentation change. I think it’s a good rule that everyone should follow as it benefits both the user and the project’s other developers.

Is the documentation for your projects all contained within the same repo as the code (and if so what are you using to render/view it) or do you just require an accompanying PR to wherever your docs live?

Same repo.

I think that is a dogma future software developers seriously need to reconsider. Naturally, you are free to impose whichever dogmas you believe in for your own code bases.

Why do you believe it to be a bad rule?

I don't know if it is a bad rule. I am just questioning the return of investment on human written documentation.

From my perspective, it seems to have diminishing value as we are getting other means of disseminating software documentation.

Are you seriously questioning whether there are significant productivity improvements and customer satisfaction gains associated with having timely and accurate documentation?

Also, how do you disseminate documentation that does not a priori exist? It doesn't come out of thin air.

I am seriously questioning a lot of things, and so should you.

As some of your sibling commenters have also pointed out, my proposal is just that some types of documentation is becoming obsolete. Ie. LLMs will probably rely heavily on tutorials and less structured documentation to explain how certain functions work, in what case we don't have to write that out.

And that is why it is difficult to learn new things.

I want to read documentation but then I have been programming for 45 years and am used to reasonable documentation.

If you are not experienced in language X the being told to look at its source code to see what and how it works is not good as the reason you are asking is because you don't yet understand X. Documentation has to be written assuming you don't know what is happening.

Even UNIX/Emacs documentation is frustrating as if you know Unix/Emacs than searching will give the information you need but if you have not user that port before then the documentation is opaque.

I suspect that documentation works when it is written by a separate team than the developers of the product and the documenters use the product.

My expectation is that a LLM can assist with exactly this. It would even be able to be lead by what you tell it that you know – and it can do it much more cheaply than humans.

Unfortunately current LLMs also produce false code. Possibly because they do not have enough correct documentation to build models from.

Reply on news.ycombinator.com