Hacker News new | past | comments | ask | show | jobs | submit login
The State of Apple's Developer Documentation (mjtsai.com)
371 points by bangonkeyboard on May 20, 2019 | hide | past | favorite | 234 comments

Oh man, this has been suuuuch a pet peeve of mine.

There is so much buried, incomplete or otherwise missing documentation on Apple's side, and every time anyone complains about Electron and wonders why nobody wants to build native apps anymore... this is a huge factor why. Meanwhile, any Cocoa devs on Twitter scoff at this stuff being difficult to find and learn.

It goes deeper than this, too - there's a litany of Apple dev forum threads that Google has half-spidered and are behind a login screen. Or the fact that some of the release notes for point releases of macOS will have crucial details that you'd otherwise miss - just a few months ago I learned that watching the mouse in a specific way can completely disable smooth scrolling.

I dislike Marzipan, personally, but I wouldn't be surprised if a huge motivating factor for the project is the fact that parts of AppKit require wizardry on a dwindling level. I've had developers from Apple lament this to me in person, too, and nobody ever seems to have a clear reason why it's such a clusterf...

You say it like Electron documentation is any better, for one, the scope of a project like electron is many orders of magnitude smaller than the Apple ecosystem APIs and second, it is barely any better. This comes from someone who has done a fair share of developing in both.

What I hate most about electron is the never ending pointless churn in quest for "modern".

Breaking changes like this that provide no real value is standard modus operandi: https://github.com/electron/electron/pull/16570

Something as simple and fundamental for desktop applications, Instance Management, changes every release or so, and is primitive at best (a simple mutex and event, with no way to pass metadata other than the instance flags).

The portable builds are half-ass too, can't build a separate 64bit and 32bit version for windows without building twice and cleaning up.

Many many other issues like that, it is a case of torture by a thousand cuts and forever trying to keep resource consumption under control.

Electron sounds good in theory, but in practice it barely scratches "good-enough".

Core Electron documentation is akin to wondering where the docs for NSApplication are. They exist and are easy to find, but they might be confusing at points if you don't get it, or it's not documented - but it's a smaller surface area.

How you build things in Electron is akin to the web rendering API, which has ~20 years of backwards compatible guides and documentation. There is, full stop, not a single thing out there that is as well documented as HTML/CSS/JS.

(Edited to note that parent comment significantly edited since my reply. I'm not debating in this format.)

HTML, CSS and JS, as open standards with multiple vendors, have the amazing advantage that if you can't find good developer docs you can just read the spec and it will tell you precisely how something works.

I've been doing this for 10+ years and the absolute last thing I'd do is stop and read a spec from them.

Not that I don't think it's useful, it just (in practice) ends up with edge cases per-browser that I'd rather find out upfront.

Edit: The above probably sounded more harsh than intended, haha... don't take it as derision please. Just noting my thoughts on specs.

> if you can't find good developer docs you can just read the spec and it will tell you precisely how something works.

Or rather, how it is supposed to work, but good luck with anything non-trivial. Though the state of things is much better recently than it used to be, but still a long way between implementations and spec.

Are you reading W3C or WHATWG?

I'd say that AutoLayout is much better documented than CSS; because it is a much better concept in the first place.

AutoLayout is amazing. I love it and personally think it's better too...

...however, when it first got added to iOS, Apple notably had crappy documentation for it, and the performance was abysmal so it had uptake issues where people would still resort to manually judging frames.

Moreover, it doesn't matter. CSS is a juggernaut and it's not going away anytime soon.

Don’t forget the secret knowledge that is passed on via archive WWDC videos and is forbidden to put into written form, lest the heathens would stumble upon it via Google.

Forever be damned the heretics at asciiwwdc.com!

Or the classic "burn a TSI to solve some esoteric issue that documentation might've helped with".

Easier to just throw the system libraries into Hopper, honestly.

Is Hopper better at ObjC than IDA Pro? I’ve tried going through UIKit once with IDA, but it was very tedious due to objc_msgSend...

It does has better handling for obj-c messages. IMO it's not as good at C or C++ as IDA (I haven't tried Ghidra), but tracing through what messages are sent is often the thing that matters for apple system frameworks.

I personally prefer it to IDA Pro and Ghidra. It's not always the most accurate but it generally does the job pretty well for what Clang produces for C and Objective-C.

"Sorry, this functionality is not covered by Developer Technical Support"

Usually they'll refund your TSI in that case, so the only thing you lose is your time?

The Apple website has transcripts of the the videos, and there's a third-party website that allows you to search them


>there's a litany of Apple dev forum threads that Google has half-spidered and are behind a login screen

I often experience this too. Haven’t tried it yet, but I wonder if you could access the content by changing your user agent to one of googlebots.

The answer to your last question is pretty obvious. AppKit is from the NextStep era:


Yes, which is also where the odd coordinate system and so on descend from... the annoying thing is it still works fine, but it's too large of a surface to enjoy developing in without proper docs and so on.

Err...the "odd" coordinate system is the Cartesian coordinate system from...math.


It is also the coordinate system of the graphics model(s) underlying all this: Postscript, PDF and CoreGraphics.

As UIKit shows, it is fairly easy to transform the coordinate system if you want a different one.

Plus there's also NSView.isFlipped if you want the UIKit behavior.

It's "odd" because the vast majority of UI libraries use top left, not bottom left. NSView being flippable alone confirms that it's an expected style at this point.

Anyone who did middle school math knows it's Cartesian. ;P

NSView has been flippable since the NeXT days.

People whining about Electron is a pet peeve of mine for this reason. Electron exists because of the sorry mess of half-supported fragmented junk that desktop UI development has become. If you hate Electron don't blame Electron. Blame OS vendors.

Not sure why this is getting downvoted I think it's dead on. Yeah desktop's always been fragmented, but it hasn't always been in today's state of utter neglect. Look at Windows - wpf was powerful, elegant, and ahead of it's time. Now it's abandonware with nothing to replace it (please don't say UWP). To reiterate - right now the world's dominant-by-a-mile desktop OS has no viable modern 1st-party native UI toolkit.

I wouldn't say WPF is abandonware, just look at the efforts to modernize it with .NET Core 3.0 (and as someone already pointed out: WinUI)

AFAIK, those efforts are just trying to make it usable from Core 3.0 - they're not doing anything to address the verbosity and performance issues.

They've also been doing work for making it easier to call WinRT APIs or introducing UWP controls (through XAML Islands) in both WPF and WinForms... A bit of a stretch, but this way they're both inheriting all the work they've done before for UWP. I think they also announced something about DPI awareness that won't be backported to classic .NET because it required runtime changes

Does any of that sound like it's even in the neighborhood of what's needed to you?

Not at the moment, I currently work as an iOS developer. But I'm working on a cross-platform app in my spare time (currently I'm only developing the iOS and Android frontends, while I ramp up the core), and when the time for the Windows frontend will come I'll probably pick WPF with XAML Islands when running on 10

Electron hater here, desktop UI has always been super fragmented. Electron does cross-platform, and it lets people deploy their cheaper-to-hire web developers on desktop tasks, plus its free, hence its popularity. As much as I love other toolkits I'm not sure anything else checks those boxes

QT comes close, but it ain't free. WinForms also comes close, but its old and whiny kids think its ugly. GTK comes close, but you can't use your web people to program it...

I'm the greybeard that likes WinForms, but it has a couple of massive blind spots due to its age - the big one is that it's not "responsive", and copes badly with high-DPI displays. This is still visible all over Windows 10, as they only managed to convert some of the system config UI to Metro.

Responsiveness is extremely hard, and modern web and Electron have mostly got it working pretty well. This does come at a cost of complexity and CPU. To me there's probably more mileage in trying to resource-constrain Electron than build yet another new system and wait for its adoption.

Highly agree with the last point. Electron bloat and slowness are real, but that’s not the whole story of why so many Electron apps are awful platform citizens. If one were so motivated, they could make an Electron app that passed the smell test, and didn’t try to run megabytes of node_modules-black-hole JS per tick. It still wouldn’t be as nice as a true native app, but it’d be a lot better than the usual offenders.

Yup... a shitty app written in X is a shitty app where X is any language, platform, or framework. You can write non-shitty apps in Electron/JS but you have to actually pay attention to resource use, reducing dependencies, styling to match the host platform, etc.

It's truly hilarious how much legacy config/settings stuff there is hanging around in Windows 10. I kid you not, the click path for me to change my USB network adapter between DHCP and static IP is:

Windows key -> Gear icon -> Network & Internet -> "Ethernet" -> "Change adapter options"

Now I'm in the legacy "Network Connections" explorer window, and I double-click my adapter to open the legacy Status panel, where I click "Properties". Then select TCP/IPv4 and click "Properties" again, and finally there's a panel to actually switch it and enter network details.

> References QT as a solution > Calls web devs cheaper to hire, a gatekeeping tactic that shows up in every discussion like this (market salaries actually indicate the opposite is true here...) > "whiny kids"

Yup, this seems par for the course.

Desktop UI has to be willing to compete on Electron's merits, that's the game now. It will die otherwise.

Dismissing others' thoughts is a gatekeeping tactic, too...

>Desktop UI has to be willing to compete on Electron's merits

That's a pretty low bar. None amazing desktop UI I've seen has been non-native.

Then you're using a select few apps that fit your use-case.

The merits of Electron are explained, at length, elsewhere, and the market has spoken multiple times as to why people pick it over alternative environments. Microsoft outright courts the HTML/CSS/JS crowd because they know it matters, and that's where the developers are. Google does the same, FB has been pushing the model for native apps in more ways than you can count for years now.

It's not going away, and it's eating every Desktop GUI framework's lunch. A GUI framework (like AppKit) cannot stand against something like that without Apple actually investing in it. AppKit (or whatever they use, ala Marzipan) needs to strive to be as easy and straightforward to use as the web, or it won't matter. Comparatively few people actually care about writing a GUI and just want it to work, the interesting things are elsewhere... so you need to offer something that "just works" and is easy to debug.

(Qt is not this)

Also, "Native" is a horrendously overloaded term in these discussions. When saying it in the context of Qt, for instance, it's incorrect - Qt draws custom controls on the different platforms. A good example that I hit daily is Dolphin, it simply doesn't look correct on Mac even with the Qt switch. It feels like a Windows program shoved into a foreign OS, much like GTK does on Windows.

> the market has spoken multiple times

Every time i hear "the market" speak is to complain about Electron's resource use. Most of the time though "the market" has no idea why their computers become slow and they blame the computer itself.

The choice for Electron isn't done by "the market", it is done by the developers.

Developers are the market in that talking point, not the end users. If you have a choice between your standard desktop GUI toolkits (AppKit, WPF, Qt, etc) and the web toolkit, your prospective user market _of these toolkits_ are developers.

Developers overwhelmingly choose the latter. Thus, the market has spoken on the matter. If you (or anyone) want it to be reversed, then you need to complain at the desktop GUI toolkit makers enough that they invest time, resources, and so on to make them as approachable and "just works" to compete with the web.

The web platform won, insofar as desired common rendering APIs go, and that's the game now. That we're even still debating this in 2019 is ridiculous.

What market?

The one of developers that want to get payed, but refuse to pay for their tools?

Who pays the developers?

Scumbags peddling BS social apps we don't need.

>Then you're using a select few apps that fit your use-case.

Please enlighten me of the apps I miss.

>It's not going away, and it's eating every Desktop GUI framework's lunch.

Not for any app that matters. Form-based apps and glorified chat apps like Slack and FB, perhaps...

> glorified chat apps like Slack

Sure, let's just call the app that many many tech teams use as an app that doesn't matter.

It's not perfect. But it's certainly not insignificant.

It's also not a poster boy for a good app, Electron or not. It looks uglier than plenty of native chat apps and still manages to take up an amazing amount of RAM doing absolutely nothing.

If you mean Slack, they have announced at Google IO that they will migrate to a PWA.

Check the PWA and what is coming to the Web talks.

One reason less to bother with Electron.

So they're moving from one chromium-wrapped desktop web app to another (or, really, they're changing the backing library/framework).

Do desktop PWAs have access to native APIs as a native app would? That's a draw of Electron but not sure why anyone would want it in an application like Slack that works just fine in a browser tab.

I only have one copy of Chrome on my computer.

Yes, PWAs have different levels of access to host APIs.

I'm really not sure what an "app that matters" is. Spotify uses electron, if that matters.

And thankfully was shown at the PWA talk at Google IO, as where they are going next.

AFAIK, Spotify uses its own framework around CEF

Qt (LGPL-3.0, some parts GPL-3.0) is as free as GTK (LGPL-2.1+)

As a user i'd rather blame the developers who made the choice to use Electron despite its drawbacks for users been repeatedly mentioned every single time Electron itself is mentioned.

Some personal favorites, culled by searching my source code for swear words:

NSTitleBarAccessoryViewController lacked documentation from the time it was introduced in macOS 10.10 until recently (perhaps Mojave? That's when I first found it). There was literally nothing except the header file and the announcment in the release notes for the OS. It was also full of bugs that rendered it unusable for my application.

Overriding -scrollWheel: has all kinds of nonsense side-effects. These are only documented in release notes. Scroll wheels in general are way more complex than you'd imagine. If it weren't for Chrome's open source Mac code, it would be a complete mystery. See the investigation here (search for "of mice and men") for what Apple should have documented: https://chromium.googlesource.com/chromium/blink/+/d40e271ac...

Passing a constant buffer to a fragment shader will cause it to be truncated at 64k on some graphics drivers. Not a bug, just an undocumented limitation. Doesn't happen on my computer. That was fun to figure out.

NSMapTable with weak keys and strong value leaks the values, according to an archived document. The main docs say nothing on the topic.

If you'd like to know why an exception was thrown, you have to print the value of the proper CPU register. On x86-64 it's $rax. As far as I know this is an oral tradition, passed down from senior developer to junior developer.

If you want a daemon to survive the user logging out and logging in, you have to use a barely-documented function (bootstrap_parent) which is only mentioned in a now-archived tech note.

> Passing a constant buffer to a fragment shader will cause it to be truncated at 64k on some graphics drivers. Not a bug, just an undocumented limitation. Doesn't happen on my computer. That was fun to figure out.

That doesn't even begin to scratch the surface of OpenGL bugs on Apple devices. Many more are documented here: https://github.com/servo/webrender/wiki/Driver-issues

OpenGL is technically deprecated on Apple's platforms, so you're not likely to get much support either…

> If you'd like to know why an exception was thrown, you have to print the value of the proper CPU register. On x86-64 it's $rax. As far as I know this is an oral tradition, passed down from senior developer to junior developer.

This varies based on the calling convention and signature of the the method that the exception handler puts a breakpoint on. With objc_exception_throw on x86_64 the value should be in $rdi ($arg1) in LLDB.

> If you want a daemon to survive the user logging out and logging in, you have to use a barely-documented function (bootstrap_parent) which is only mentioned in a now-archived tech note.

It's also mentioned in Mac OS X Internals: A Systems Approach, FWIW.

It’s always a good sign when the document that explains a piece of functionality no longer bears the same name as the operating system it purports to document.

This comment nicely sums up one of the things that's wrong with the Apple ecosystem --- apparently, whatever backwards-compatibility Apple does manage to have gets dismissed by developers because "it's old".

...and then they wonder why they can't find the old docs that actually have what they need. Apple thinks the developers don't care, and vice-versa. It's a cycle of negative feedback.

On most other platforms, the assumption is that things will not change between versions, and changes are explicitly mentioned and documented when they do occur, but Apple and its developers seem to have the exact opposite mentality.

I hope you didn’t imply that I’m what’s wrong with the Apple developer ecosystem. Old is fine, as long as it is still accurate. I have spent more time than you could imagine digging through ancient cocoadev mailing list posts and WebKit Trac bugs in order to debug problems with my apps. There is nothing more frustrating than having the only available reference be out of date, and having to synthesize the gaps.

That’s kind of hard to avoid if it’s a physical book and the subject changes names.

I think his point is that it should be documented online, in an ever-green knowledge base...

It's a third party technical book, not an Apple document. No reason to expect it to be reissued because of a later Apple marketing decision.

> It's also mentioned in Mac OS X Internals: A Systems Approach, FWIW.

It's funny you should mention this. After someone sent me an amazing pull request using this call, I thought "hm, this should be in Mac OS X Internals: A Systems Approach. Why didn't I see it?" So I looked it up, and yes, it's there, but there's nowhere near enough context or description for it to be of use to anyone but (at most) the author. Here's what it says:

The /usr/libexec/StartupItemContext program can be used to run an executable in the startup context—that is, the context in which the Mac OS X startup items run. It works by calling bootstrap_parent() repeatedly until it has reached the startup (root) context. It then sets the port as its own bootstrap port, after which it can execute the requested program.

The automatic relaunching of servers by the Bootstrap Server is useful for creating crash-resistant servers. However, it is neither necessary not advisable to create production servers by directly using the Bootstrap Server interface. Beginning with MacOS X 10.4, the launch API, as exported through <launch.h>, should be used. With this caveat, let us look at two examples of using the Bootstrap Server interface.

[an example that shows how to list all known services]

[a rather complex example that creates a bootstrap service and maybe uses bootstrap_parent somewhere]

There are bits of wisdom in this wonderfully written (and of course now obsolete) tech note:


But of course, most people just copy-paste from the code Apple has (I would guess grudgingly) made open-source and we hope for the best.

Yup! I mentioned in another comment here, but overriding scrollWheel can completely kill smooth scrolling and is only mentioned in some release notes.

It's crazy.

It is mentioned a few times, but never w/ any reference or explanation :-) Could someone please provide some pointers on this?

So, I know they were in the 10.9 release notes, because 10.9 was where smooth scrolling was introduced. However... as is typical, I cannot even seem to find those release notes now?

Someone appears to have mirror them in a gist, so open this (https://gist.github.com/zwaldowski/8710fddc8b0b39d2c152) and ctrl+f for "Responsive Scrolling".

> Do not override -scrollWheel: in an NSScrollView, NSClipView subclass, or in the document view.

> If you'd like to know why an exception was thrown, you have to print the value of the proper CPU register.

I'm not sure what you mean. To see why an exception was thrown you can call [-NSException reason][0]. If you're stopped in your catch block in the debugger, it's as simple as typing:

> call (NSString*)[e reason]

Assuming your exception is named "e".


I read the "Of Mice and Men" investigation. It was a good read. But I guess the kicker is that this code is in fact written by Apple for WebKit long before Google forked Blink (do a git blame; and see notes that "if you linked on Tiger or above"). I would've thought for all the vague public-facing documentation, Apple's internal documentation must be better. I guess that's not so.

If the Metal debug layer doesn’t warn you, then it is a bug (either in the driver or in the debug layer depending on the intended behaviour).

A Cocoa oldtimer on #macdev argued with me when I pointed out that it's hard to find good resources for Cocoa dev. It's so bad that I sometimes try to repurpose iOS dev resources (like Youtube videos) for Cocoa dev.

They said that was nonsense, that I have to be expected to do some reading instead of being spoonfed (which isn't what I was asking for, it was pure condescension), and linked me to this: https://developer.apple.com/documentation/

> and every time anyone complains about Electron and wonders why nobody wants to build native apps anymore... this is a huge factor why


The most frustrating thing is when the docs have that "this document is no longer maintained. Please see /documentation/whatever for the latest version" but when you go the link it ends up just linked back to the place you came from. I guess that means the unmaintained stuff is still current? I don't know though because it's still all Objective-C, so I have no idea what the current best practice is supposed to look like. For a trillion dollar company it's kind of annoying that they can't hire somebody to do the docs. For MacOS dev there are basically no third party resources either. The last book is from Swift 3. It's better than nothing, but not much.

The "this document is no longer maintained" notice is on everything that's no longer being updated regardless of whether or not there's actually a replacement. Sometimes it's actually still up to date, sometimes it's out of date and there's something else you should be looking at, and sometimes it's just plain out of date and the only newer source of information is a WWDC session from two years ago.

What made Apple think it was okay to abandon their documentation, just decide not to update it without a replacement?

Insufficient pushback from developers?

due to the fact that they simply have no choice but to use apple dev tools. Or at least that was true on iOS until recently.

That, plus the fact that Apple having a monopoly on the store relieve them from any kind of pressure, because no matter how the dev feels about it, they’re going to give 30% commission to apple.

Give them a break, they're a small, resource-constrained company.

I came across the EXACT same thing. I just wanted to do something as simple as “give me an actual core dump instead of a crash report in Console.app”

Found some obsolete docs and they linked back to themselves. It’s absolutely unacceptable. Man pages are better, except Apple’s often don’t cover their weird, uncommon behaviors.

FYI, there is a Swift 5 book available now.

In the late 90s, Apple's Developer Documentation (for different products of course) was truly exemplar.

Old timers may not realize how far it's fallen/not kept up.

I remember reading it like a book and at the end I had a really good idea how things work. MS documentation was also quite good if you had the MSDN CDs.

Yep. Not just API level documentation (not just), but narrative overviews explaining the concepts and models and how everything went together. With just the right amount of example code.

I learned what good developer documentation could be from it!

Apple really does need to get on top of this. It’s easy for old timers to miss as in general you stop looking at things like the programming guides and end up straight to the class reference which generally is still ok. But one of the things about Apple’s stack is that it is built on a lot of years and layers of and is generally not as approachable for someone just starting.

The docs like the programming guides and the framework overview docs really help with getting your head around why things work the way they do. I’d even say that a lot of the frameworks are built with the idea that you have read them. Most developers I know who worked with obj-c and OS X really loved the cleanliness and care spent on this aspect.

I don’t know if they are trying to outsource this work to save a little money or if it’s just neglect but the end result is going to hurt them in the long run.

Don't feel bad about it, if you did.

I launched a combo macOS/iOS app last year and wrote (yet-another...) framework to bridge the gap between AppKit/UIKit. There's an insane number of minute differences, even with Apple trying to make it better behind the scenes (e.g, NSCollectionView _can_ have a similar API to UICollectionView, but it's really not the same beast - it's much easier to tank performance on it).

Apple has, IMO, hands down the best UI framework(s) outside the web platform, and they're outright crippling them by what they're doing here. The AppKit community also needs to do their part and not be so resistive to modernizing how it's all learned.

tl;dr it sucks.

There are barely any Cocoa courses or books that have been updated. All the learning industry is focused on iOS now.

I suspect Apple's culture of not really caring about backwards compatibility and otherwise technological churn is mostly responsible for this; e.g. if I wanted to write Windows GUI app that'll run on everything from Win95 to Win10 and probably for the forseeable future, I'd choose Win32 because it's stable and well-documented. On Linux, a combination of POSIX and Xlib would probably have similar stability. But I'm not sure what the equivalent would be for the Mac...

That said, I've noticed MS's documentation quality also take a nosedive in recent years, notably around the time it moved away from MSDN (and introduced a huge amount of formatting errors.) A lot of useful "KB" articles and downloads also mysteriously disappeared. Fortunately I still use "WIN32.HLP" which basically covers the core part of Win32.

I love how they go to great lengths to describe and recommend that for Win8 and above you should use Pointer API instead of the "legacy" mouse and touch events, because it'll also handle Pen too. Yet when you actually go to click on WM_POINTER*, they are, just like Apple, in an archived section. Tapping on the "see latest doc" just takes you to the home screen. Yet, WM_LBUTTONDOWN takes you to the latest updated version. Talk about a confusing mess.

docs.microsoft.com PM here. Thanks for the feedback - I am routing this to the content team so that we can see what we can do to improve this situation.

Well, since you are here... can we have something like the old MSDN CD CHM files and/or WIN32.HLP files (ie. a simple offline version of the documentation that includes everything)?

Almost every other mention of Win32 documentation here and on Reddit has someone mention that they use some archived version of WIN32.HLP (or less often, CHM) instead of the sites because it is simpler and faster. But this documentation only covers the circa late 90s APIs and doesn't have any newer stuff and to view .HLP files on Windows 10 requires some hacking around (honestly it is absurd to break the help for several thousands applications and make several ebooks unreadable, but i guess it isn't something you can do anything about even if you wanted).

Considering everything is static (and really, some of the documentation entries read the same as they do in WIN32.HLP from the mid-90s) it should be possible to make a CHM (or several of them) with the content available for download (but please not yet another custom help viewer, CHM is fine).

TBH i do not have many hopes for this (i think this is something people ask for more than a decade), but it costs nothing to ask, so there you go :-P

The latest you can download offline might be this:


(Best to get a copy while you still can...)

Thanks, i didn't knew about that :-).

This comment alone, and the lack of any comment by any Apple rep so far down the comments, makes me think that I did the right thing ditching macOS as my main web development workstation in favor of Windows.

There are AppKit devs who lurk here, but due to Apple's (somewhat written, somewhat unwritten) policies, you'll rarely if ever see them out themselves as such.

I remember I did a double take when I saw Corbin answering questions about NSTableView on StackOverflow, felt like hell had frozen over.

Don’t get too excited. Responding here is easy, doing something about it is much harder. MS has gone downhill since the 90s. The MSDN CDs used to be great but somehow they decided they should make things worse regularly. The current web site has terrible search, has lots of links broken and the content seems mainly auto generated. Not a very good experience if you need to find something.

Point taken - we always definitely have room to improve. There are two avenues you can submit feedback: https://aka.ms/sitefeedback, for anything that is related to site functionality, and the footer of each article, where we integrate GitHub feedback, where we enable GitHub issues.

If, for some reason, the article you are looking at has issues but no feedback affordance, use our site feedback channel or DM me on Twitter (@DennisCode) - would be happy to route the feedback and make sure we address it.

We triage those items fairly regularly.

Not to pick on you personally, but this habit of the new Microsoft irritates me to no end. Microsoft's response to everything is "give us feedback and we'll fix it"

Do people at Microsoft not use their own products, so they don't know something's broken unless a user reports it ?

Using users for QA has made Windows 10 the worst Windows I've ever used and it's something to see that same attitude permeate every Microsoft product.

Just wondering: How long have you been working at this and are you personally happy with the state of things? Do you even use the site? Vendors always ask for feedback but a) when you submit feedback, it usually disappears in a black hole b) if they actually used the stuff themselves they would already know about most problems.

I don't want to attack you personally but MS support always has been a black hole and when I look at the feedback forums there are always these generic messages ("We are sorry,. Pleas help us to understand") that either are written by robots or certainly feel like that. But nothing ever gets resolved, there never is a direct answer to clear problems.

What makes you think that you should expect that someone working at Apple, who can fix your issue, will materialize in the comment section of Hacker News and solve your problems (and then reply to you saying that they will do so)? It's nice when relevant people step in and help, but there's a proper channel for this feedback (even if you don't think it's going to be heard).

This isn't a great answer, because there _is_ some literature to point to concerning how feedback (bugs and otherwise, regarding engineering) is handled at Apple: https://www.corbinstreehouse.com/blog/2019/03/the-sad-state-...

The game that Apple's dev evangelism needs to play is the same one that MSFT/Google/etc play. Apple gets a free pass because they've had a largely devoted (almost cult-ish) fanbase of software developers (of which I count myself). They're starting to piss them off, though, and that has cascading effects.

Lobbing things over the wall doesn't work anymore.

If you read the article (I'm generally aware of the issues mentioned, FWIW), there isn't really much it tells you to do other than file bugs.

I did read the article, considering I linked it in the first place. The snark isn't necessary.

The ending of that article is a very resigned "this is all you can do. This is why it's this way, though.". The article is absolutely a criticism of how the bug process works.

The entire point of all of this is that Apple needs to play the game better. You have a weird habit of popping up in every single thread to defend them, and I've noted your past associations with them in other threads, so I'll probably not bother responding to this further.

> I did read the article, considering I linked it in the first place. The snark isn't necessary.

I meant this more as "if you go back and read the article, looking for the part I mentioned, since you may have missed this", which I included because you said my answer wasn't really great "because of so and so" even though it basically just restated what I had said. I know about the problems you're mentioning are: you know how I would.

> The ending of that article is a very resigned "this is all you can do. This is why it's this way, though.". The article is absolutely a criticism of how the bug process works.

> The entire point of all of this is that Apple needs to play the game better. You have a weird habit of popping up in every single thread to defend them, and I've noted your past associations with them in other thread

Again, I'll freely admit I generally lean towards Apple because of the amount of time I've spent associated with the platform/tools/company, but I'm not disagreeing here: I'm with you 100%. As Corbin notes, however, filing bugs is more likely to get your issues noticed (and possibly responded to) than posting it four comments deep on a thread that admittedly has a higher-than-normal chance of getting clicked on by an Apple engineer. I guess if you know an engineer you might be able to see if they can institute change, but even then I'm not sure that would help much. Getting articles like these on the front page of Hacker News regularly might, though…

Yeah but this is hackernews, if there aren't apple devs looking at this thread(or someone forwarding this thread to an apple dev contact) it'd be somewhat amazing.

Making devs feel like they're being listened to is an important part of attracting devs nowadays, which ofcourse apple says they're above. Apple famously doesn't chase anyone after all(with predictable results).Instead apple evangelists like you have to take up the standard - which doesn't assure anyone.

There's almost certainly Apple engineers looking at this thread, but I'm not confident on their ability to change anything meaningful or talk about what the situation looks like internally.

At the very least they could mention that there is an internal process going on to improve docs. the fact that there haven't been any is an indication of a growing trend at apple going the same way as Samsung/Sony - "who cares about devs?"

Apple doesn't seem to encourage this kind of behavior :(

"Proper channel"... :)

That vastly more critical Facetime/facepalm issue certainly went straight to /dev/null , so ... thanks for the laugh, I guess.

While you're here the rename of the URLs has caused me pain. For example (here on Task.Unwrap)


The code sample has broken links, the correct pfxteam blog is: https://devblogs.microsoft.com/pfxteam/whats-new-in-beta-2-f...

It would be great if 404 page could show the posts for that day for the 4-Nov-2009 time period

I don't know what the current MS doc situation is, but years ago when I left Windows dev to move to iOS I really missed the MS docs. The big reason was that they had tons of examples. I used the XPath MS docs for many years because they had so many clear examples.

I feel like maybe hyperlinks in developer docs were a bad idea.

Writing technical documentation as if it would be published in thousand page tomes (because it would also be published that way) may have encouraged better writing and organization.

> I suspect Apple's culture of not really caring about backwards compatibility

Not only that, but there's a famous article in Apple University about how no documentation is a good thing and a key part of Apple culture.

Can you share a copy or a citation? I wasn't able to find this.

That's kinda meta, honestly

This explains so very much - imagine trying to hack on something as big & as crufty as iTunes without guidance.

Ah, yes. Apple seems to almost spitefully change document URLs on a regular basis too. (Which would be a little less terrible if you could simply re-Google the replacement link but you can’t.)

My favorite experience was looking for virtual key codes. A few years ago, there was a point where the only place you could find the values of (arbitrary) virtual key codes for input events was in a printed copy of Inside Macintosh for System 7. Was this some ancient Mac? No, it was needed on OS X, by their “preferred” Cocoa/NSEvent no less, and their modern hardware was sending the same codes. They eventually “fixed” this by putting the information inside Carbon.framework header files (which will most likely just disappear in the next OS update).

> Which would be a little less terrible if you could simply re-Google the replacement link but you can’t.

Not only can you not do this, Apple's own site search doesn't bring them up. They just get lost :(

That’s how modern design works. MS is using the same tech of broken links and empty pages.

I'll admit I get lost in the documentation (and various archived pages) from both companies, but at least I can still do a `site:docs.microsoft.com` Google search and get results! Banning search engines from your clearly archived content seems unnecessary and extreme ...

“Banning search engines from your clearly archived content seems unnecessary and extreme ...”

Let’s hope MS won’t incorporate this “feature” in the race to make their docs worse:)

Good news, you can find Inside Macintosh online (via Google) and in https://developer.apple.com/library/archive/documentation/ma... (Macintosh Toolbox Essentials) it lists the key codes graphically on page 2-42 and 2-43. There's also https://developer.apple.com/library/archive/documentation/ma... (More Macintosh Toolbox) and https://developer.apple.com/library/archive/documentation/ma... (Imaging with QuickDraw). Not that I'm suggesting this solves the problem -- I still had to use Google to find these, and outside of WWDC, I've yet to see Apple publish developer documentation as nice as this from the early 90s, or the WebObjects guides from the early 2000s (that you can also still find online). Maybe the Swift manual from https://docs.swift.org/swift-book/ (and in Apple Books store) or the CarPlay guide? https://developer.apple.com/carplay/documentation/CarPlay-Na... I do kind of miss when guides were more complete, such as the Automator Programming Guide http://citeseerx.ist.psu.edu/viewdoc/download?doi= (It appears it was removed in 2016 from developer.apple.com)

It is kind of funny that one can Google the obsolete printed text more easily than the online ones.

(Macintosh Toolbox Essentials)

This brings a big smile of nostalgia to me - I remember reading this massive book and trying out all the system calls on my Metrowerks c++ compiler (system 7).

I probably still have a copy of it lying about somewhere...

The state of the docs is what got me to dump all of the links I'd been collecting to useful, but hard to find docs in to a small website -- https://www.iosdev.recipes/

Some things are incredibly useful and well organized, but completely blocked from indexing, like the documentation for xcconfig files: https://help.apple.com/xcode/mac/current/#/dev745c5c974

Apple has been doing a great job in some aspects at documenting more and updating things gradually, but at the same time, has been hiding more and more of the "old" docs and it's a shame since many of them are still correct, relevant and useful.

I can find some (albeit very poor) results: https://duckduckgo.com/?q=xcconfig+site%3Ahelp.apple.com

This query displays nothing, for me - just the link to /xcode/ on their site.

There's only one actual website backing the help documents, so that's what it'll link to. It does, however, manage to pull out the text and serve it to you, which I guess is sort of a win?

Indeed. I had some older Objective-C code that used NSCoding and NSArchiver that I needed to update to the modern NSSecureCoding and NSKeyedArchiver. Serializing and saving objects used to be well documented:


These sorts of guides seem to no longer exist. I was left to figure out NSSecureCoding and NSKeyedArchiver with no code examples nor guidance from Apple. Just the methods barely documented with most of them deprecated:


Apple docs used to be great. They've become pretty awful. Has Apple even published a tech note in years?

Apple docs were never great. They were just better than average in an era when documentation overall wasn't that good. They have always had the broken links, public APIs that are undocumented, crucial information that only exists as a comment in a header file, methods with one line of description that just restates the method name with spaces, and bad sample code.

What has happened is that documentation elsewhere has improved. Mozilla has invested heavily in documentation and now the web platform has great docs. Apple has done the bare minimum for years and it shows.

IDK what time period you're talking about, but I thought around 10 years ago it was pretty good. You could download and install all the documentation locally, they had pretty thorough class documentation and also higher-level conceptual documents around various topics (seems like those are all deprecated now).

Was able to basically just code against the standard library and the documentation actually seemed to be one of the perks of native development, since it was all in a standard place/format with pretty good baseline quality. I'm working with a greater variety of library dependencies now and of course the documentation isn't as consistent.

It's kind of mind-boggling how Apple seems to have gotten bad at this now.

> also higher-level conceptual documents around various topics

Yes! The FOO Programming Guides and BAR References were the gold, and consequently the things that are hardest to see disappear. They explained the whys of the frameworks. And how the pieces fit together. Per-class docs are not any substitute.

I agree. The docs from that time period were wonderful. I'm shocked at how far its fallen.

"What has happened is that documentation elsewhere has improved. "

No, what has happened is that Apple is acting almost as though third party development itself is going to be deprecated at WWDC this year.

They always had issues and ellisions. This is orders of magnitude worse and suggests a significant shift in management intention, the full extent of which has not yet been revealed.

I bet they count on the community to document their stuff via word-of-mouth and medium posts. Too bad 95% of them are variations on “how to write hello world with the latest Swift syntax sugar”.

Thankfully the headerdocs are still mostly intact.

There's also an awful lot of important information tucked away in WWDC videos, unfortunately.

But will that continue to be the case as headerless Swift takes over?

Yes, that's a real problem. Currently the Apple libraries are all Objective-C, so even if you're using the Swift shims you can still use the headerdocs of the original Objective-C framework.

Same with older developer videos. There is some fantastic material that is not outdated (GCD stuff from 2011 for example) but that remains unavailable from Apple as far as I can tell... you have to know someone who has a copy. I would like to be wrong about this; someone please let me know if I am.

I was about to say, "you're wrong, I was there just last year and it amazingly showed links to all the past WWDC videos" only to go there now and realize you're right, totally right -- they've REMOVED listing any videos older than WWDC 2015 according to search filters. You can still find the old videos thanks to Google: https://developer.apple.com/videos/play/wwdc2011/210/ but who knows how long this will last?! Very, very disappointing.

Ah, they don't link to it directly now, but https://developer.apple.com/videos/archive/ is still available from last year for videos from 2010-2011. (Found the link via Archive.org)


https://developer.apple.com/videos/wwdc2012 https://developer.apple.com/videos/wwdc2013 https://developer.apple.com/videos/wwdc2014 https://developer.apple.com/videos/wwdc2015 https://developer.apple.com/videos/wwdc2016 https://developer.apple.com/videos/wwdc2017 https://developer.apple.com/videos/wwdc2018

I really wish these were easier to find, still.

Awesome, thanks! I noticed some of the older videos are listed with download/viewing links that don't actually work at least in current Safari. For example, the "Working with Core Data from iOS" one is a no go. But still very useful for the rest of the videos.

Edit: Got that one video to work by right clicking to download, and then QuickTime played it after an automatic conversion step QuickTime did. Of course it's very outdated, but still some useful info even in the very old videos.

I'd been trying to find https://developer.apple.com/videos/archive/ for a while, thanks.

Someone else in this thread linked to ASCII WWDC [0], which lets you search through all available video transcripts. It's worth noting that some older videos have no transcript, and some newer videos says "Awaiting Transcript". Each session includes a link to the video and slides.

If you try browsing all videos [1] you can only view as far back as WWDC 2015, I think this is because the searching and filtering capability of these pages is being handled entirely on the client. You can access older WWDC videos by manually editing the year in the URL, although it only seems to work for going as far back as WWDC 2012 [2].

You can still find this content by using the regular developer search [3]. Searching for "grand central dispatch" and selecting the Videos tab shows "Mastering Grand Central Dispatch" [4] as the first result, which I believe is the material you're referencing.

Since we're on the subject and you appear to be familiarized with the content: do you have suggestions for WWCD videos worth checking out if you're interested in learning more about macOS?

[0] https://asciiwwdc.com/

[1] https://developer.apple.com/videos/all-videos/

[2] https://developer.apple.com/videos/wwdc2012/

[3] https://developer.apple.com/search/

[4] https://developer.apple.com/videos/play/wwdc2011/210/

Sample code for a lot of the older ones has gone missing, too. "Advanced NSOperations" is the one that springs first to mind. Great talk.

I've always found online docs to be a little bit lacking. Used to be, if you bought a compiler like Visual C++, it came with a book (printed on paper) that was readable and useful and helpful. Then they started migrating that content on to the web. Then they started auto-generating the web content. Then they started auto-generating some of the web content. Now if you want to learn how to use a product, you have to shell out $60 of your own money for a book that describes it.

> Used to be, if you bought a compiler like Visual C++, it came with a book (printed on paper) that was readable and useful and helpful.

Some time ago i found a copy of Borland C++ for Windows 3.1 in its original box on eBay. The box was actually a cube and inside 99% of it was books, including references and guides for everything as well as Petzold's book for programming Windows.

Sadly the cost was too much for me, but it was incredible how much documentation Borland provided (although that box was most likely an outlier, other Borland products like Delphi had more regular boxes, but still came with several books).

Having said that, in Visual C++ at least since Visual C++ 6 there wasn't much printed documentation - although the dual CD MSDN docs it came with are golden.

Ah yes the "good times"

Too bad Visual C++ was much, much clunkier than Borland C++, it was not even fun.

But true, the amount of good info found on those CDs was amazing.

Depends which versions we're talking about and if with "Borland C++" you mean the Borland C++ or the later C++ Builder.

I'm going to guess the former.

I have actually both BC5 (the last version that was released as "Borland C++" with the IDE going back to Win3.x times) and VC6 installed and have used older versions of VC sporadically.

Visual C++ pre-VC6 was indeed clunky although i'm not sure about why as i haven't used it much, but i remember it not feeling very polished. However with VC6 Microsoft pretty much made the C++ IDE and is why even today most C++ IDEs (e.g. KDevelop, Anjuta, Code::Blocks, CodeLite, etc), many IDEs in general and even some code editors have the same basic UI layout and features. VC6 is a standard and really the only thing you may miss is tabs in the editor (but there is an addon that adds exactly that).

BC5 is a nice IDE and actually, unlike VC6 (or any later version, including VS2019) is a really Iintegrated DE - the compiler is part of the IDE (you can even compile some code just by opening a text editor window and start typing code in, no need to save a file or anything, the compiler picks the source code from the editor's memory). It is also very extensible, using a C-like scripting language with dynamic typing that can access most of the IDE's features and (AFAIK, never tried it) you can write DLLs to extend the language's functionality. Personally i've only used it to modify some shortcuts from their Brief-like defaults to Windows-like defaults (e.g. Ctrl+S for save instead of -IIRC- Ctrl+K Ctrl+S...). The node-based project management also looks powerful, especially since i think you can extend it, but TBH i didn't use it much again. UI-wise it is an evolution of the original Turbo Pascal for Windows IDE they introduced with TPW 1.0 which itself was a sort of GUI evolution of their classic Turbo Vision-based IDEs introduced in TP6.

TBH i do not find either of those to be too clunkier compared to the other, but i find VC6 to have some of an edge UX-wise. Previous VC versions probably will be worse though.

Now if we're talking about C++ Builder, then yes, even BCB1 blows both of these out of the water.

Yes, I'm talking about C++ Builder

The clunkiness I referred to was not so much w.r.t. the IDE (which in VC++ was ok) but the C++ API for Windows forms (and other things)

C++ Builder was a breeze to use, on VC++ for example a slider (not sure the exact name) required you to filter for Windows events manually whereas in C++ Builder it was automatic but easy to customize.

(Then MS hired that Borland guy to come up with .NET and everything was as it should)

The other Borland C++ I used was the one where you had to worry about the memory model being Small/Large/Huge (those were not good times)

Yeah, VCL is one of the best GUI frameworks out there (although its C++ bindings had to twist and bend and extend the language a bit to work and as a result it feels a bit awkward compared to Delphi).

Although despite C#/.NET being good for that they are, WinForms even today is in several fronts (e.g. layout) worse than what you had even with Delphi 2/C++ Builder 1. It feels like it was abandoned too quickly.

I started programming in the 90s and then I often would read the documentation like a book. Usually it was well written and really easy to read.

I would plop down and read the fat volumes of the NeXTSTEP General Reference.

That was my introduction to OOP, Turbo Pascal and later Turbo C++ manuals.

I remember downloading the Visual Studio 2008 documentation and installing it locally on my PC. The docs were well put together and integrated neatly with the IDE.

This stopped when they switched to a new offline help viewer (probably for valid reasons but still) that just didn't work well enough to replace the old one for me.

That being said, most Microsoft documentation is still top notch once you use Google (or god forbid, Bing) to find the right article. I can see improvements to readability and accessibility of the site every once in a while but I kinda just want to the old docs back. They contained a beginners guide that didn't require clicking around a bunch of links to avoid the video tutorials, for example

I've been a MacOS/iOS developer for decades, alongside a healthy bit of Linux development, and more than anything this year I want to switch 100% to Linux-only development if only for the fact that Open Source still gives us the best developer experience when it comes to working things out.

If the documentation sucks - use the source. This is a lot more palatable on Linux than it is on MacOS/iOS.

That said, I do have to wonder if this is all just a bit of a side-effect of an internal re-org that Apple are preparing us for, with the move to Marzipan? I'm not holding my breath, but I find it difficult to conceive of the notion that Apple don't have something up their sleeve with the future merging of iOS/MacOS that will make us all quite devoted to their ways, yet again ..

Remember, its developers who drive computing forward. Whatever is done to the platform, it must accommodate the strategy of capture of developer mindset.

"Whatever is done to the platform, it must accommodate the strategy of capture of developer mindset."

Only if the company has a clue.

The dev docs are atrocious - especially when they were pushing swift before swift was even remotely stable. The end result is huge amounts of example code that has no obj-c code, but the swift code doesn't compile anywhere. :-/

So frustrating, even with my background.

I file reports in Bug Reporter about outdated Swift docs, and they always fix it and respond back.

I know, but I feel given the lack of stability it always annoyed me that there wasn't an automatic radar on every swift example that would break :-/

Apple’s documentation has always been patchy throughout the life of OS X IMHO.

It’s even more tragic when compared to MS who really has been the gold standard — I personally really dislike the programming model but at least it’s clear what’s available.

> Apple’s documentation has always been patchy throughout the life of OS X IMHO.

Not to this present extent. The complaints from other commenters here about AppKit developers telling them to RTFM are likely because the documentation that those established Mac devs learned from was much more useful at the time that they read it, and they may be unaware just how badly it's deteriorated since.

I spent the 90s working on NeXTSTEP software, and I think the current doc situation at Apple is crap and is an ill omen of where Apple is going.

Yeah, I didn’t mean to excuse them!

I remember when I used to actively develop Mac apps, about a decade ago, Apple actually released an XCode version where they spent a bunch of time during the WWDC dev tools keynote going over the improved integrated documentation system.

I am surprised to hear that Apple docs have gotten so bad. They used to be really good, with detailed, well written documents that not only described how to do things, but why they should be done that way.

Writing good documentation is super hard.

I try to do it for my parser (https://github.com/norswap/autumn4/) which is < 10k lines of code — both complete and useful Javadoc and a user guide. It's a lot of work, which would easily rival the programming if I hadn't had to tackle open/hard problems. Can't imagine how it must be for bigger projects.

Another issue is that documentation is not a task easily left for "sub-alterns". It requires a good deal of understanding, finesse, and pedagogy. And it actually plays nice in a feedback cycle with the programming. The documentation is where you realize your tools is nowhere near as simple and friendly as you could (easily) make it.

So the bottom line is that this requires massive investment which isn't always done this day. And personal accountability of individual developer/small team on writing docs and being into the feedback loop.

The programmers themselves don't need to do it. Apple has, or should have, dedicated technical writers to work on documentation. These are people who are knowledgeable about programming but do not write production code as their specialty.

Well, one of my point is precisely that involving programmers in the documentation process (maybe not force them to write the documentation — but review it and run a feedback loop) is crucial in having good documentation, and actually better code as well.

Of course, having any documentation is better than none...

Wait, is there developer documentation that isn't terrible, incomplete, and incorrect? Is that a thing that exists somewhere?

I've certainly never seen any of this mythical good documentation on the Microsoft side where I live, and even that is copious in comparison to the third-party stuff I've used, where major libraries have a Github readme and no more.

Apple iOS documentation in the beginning used to impressively good. Back in the ~2008-11 timeframe when I last looked at it seriously it was well organized, with plenty of samples and tutorials.

It was a nice change from the MSDN docs, where if you knew what you were looking for you could find a link, but good luck finding coherent articles or samples.

Sad to see that Apple has backslid in that department.

> I've certainly never seen any of this mythical good documentation on the Microsoft side where I live

Depends on what you're looking for. If something existed in the 90s, chances are it'll have great documentation (e.g. some people learned 3D graphics just from older DirectX documentation). The more you come closer to today, the more spotty documentation becomes.

BSD man pages. When you didn't have the Internet you depended on good docs.

Apple's BSD man pages are pretty out of date, ironically…

From my experience Qt documentation was excellent, I do not know about the recent years but the Qt Widgets are stable and do not change. Other good example is Mozilla MDN.

Yeah, MDN is good for everything. I've had multiple separate people point out issues with w3schools at various times to me and then say "but MDN has it right."

Hmmm, this is interesting, because when I was in college (early 2000s), most of Apple's docs were littered with "description forthcoming" EVERYWHERE. The only way you could possibly understand the proper behavior was to use a framework (PowerPlant), or spend thousands to go to WWDC and ask engineers. But Apple wanted everyone to adopt Cocoa and invested heavily in making it as appealing as possible. What probably happened, they hired some bright well managed senior copywriters who ran a tight ship under the Steve Jobs era and cleaned up the mess. Best practices were defined and as best as Apple could, they explained how to take advantage of OS X and iOS. I mean, important nuggets would still sometimes fall through the cracks, but for the 80% case, you had really good documentation.

At that time, Apple was known for its Human Interface Guideline textbook with full color check-lists of Dos and Don'ts that really influenced the spread of skewmorphism around to other platforms.

What probably happened is they left, and if the writers had not completely burned out, Google and Facebook do pay way better and offer much better work/life balance. So Apple is probably left with mostly new grads who don't have families and so when an exec asks them to move the documentation to iCloud, it's probably just been one mismanaged cluster fuck after another. I suspect they'll eventually finish the migration and it'll be back to world class again.

If Apple prioritized it by putting resources into it, they could have good documentation. Same route and same barrier for anyone. But it's not like Apple can't afford it.

”when I was in college (early 2000s), most of Apple's docs were littered with "description forthcoming" EVERYWHERE”

Looking back, that wasn’t too surprising. Early 2000s, Mac OS X had just shipped. Apple had managed to build a working system, glueing together highly different sound, text, windowing and file systems APIs, but didn’t know yet what the APIs that they wanted to support long time were going to look like.

They also didn’t want to say lie don’t know yet whether we will support this long term”, as that would chase away the developers they dearly needed.

My two biggest problems are all the example code that doesn’t even compile and the lack of ability to have a pdf so I can print it or use an e-ink device. My eyes are not up to reading off a screen and I am sick of getting headaches because of Apple.

Do you have a Mac ?

Because you can create a PDF from anything e.g. web pages by going to Print, selecting PDF dropdown and "Save as PDF".

Wouldn't it be cool if, Apple being the size it is, just made downloadable PDF manuals of their products?

IBM still does this in their Information Center. My experience was developing for mainframe and midranges, and even if there are hundreds of PDFs, it's really straightforward to find the right manual for the exact product version you need. You can work for weeks without Googling technicalities.

I can't praise enough how clear and well structured their manuals are. For RPG, for example, you have a complete Language Reference[1] to learn the language, and a Programmer's Guide[2] to learn how to use it. They have manuals for everything, there's 5 of them solely for TCP/IP on the IBM i!

[1] https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rza...

[2] https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rza...

PDFs used to be available. Usually at the top right of the page there'd be a link to get it as a PDF.

Actually they do:


Not all in PDF but most.

These are consumer product manuals and warranties they are legally required to provide, it's not even remotely the same.

I don't see any developer documentation at the link. IBM, for all its faults, has some amazingly specific documentation and examples that actually work.

A PDF-from-a-webpage isn’t the same thing as a well-structured, print-first, paper manual in PDF format with the right annotations.

If a webpage doesn’t have a good stylesheet for media=“print” then the browser will end up making the PDF equivalent of a screenshot.

Typography and page layout for web vs print are different enough to warrant putting a modicum of effort into making a print media stylesheet for documentation websites.

The way Apple splits its pages and the horrible print that results make this a non-starter. Also, why would I need Apple developer documentation if I didn’t have a Mac?

I went searching for PDF docs, because there was a time when Apple had a number of PDFs, guides & books available. Stumbled over https://developer.apple.com/library/archive/technotes/tn2140... from 1991. This from 1992: https://developer.apple.com/library/archive/documentation/ma... And this from 1993: https://developer.apple.com/library/archive/documentation/ma... This from 1994: https://developer.apple.com/library/archive/documentation/ma...

2001, on WebObjects: https://developer.apple.com/library/archive/documentation/Le... and https://developer.apple.com/library/archive/documentation/Le...

This from 2002: https://developer.apple.com/library/archive/documentation/Qu...

The newest I could find was this from 2017 but it was more because of branding/licensing: https://developer.apple.com/wallet/Add-to-Apple-Wallet-Guide...

Ah, this is what I was thinking of for their PDF documentation. Here's an example from 2018: https://developer.apple.com/metal/CoreImageKernelLanguageRef... -- it used to be that when you visited a page like https://developer.apple.com/library/archive/documentation/Mi... it would have a link to a PDF version of the same guide, most likely auto-generated. It wasn't great, but it served a purpose when what you wanted was a PDF to read or download for offline reference...

Also, a unique PDF: https://developer.apple.com/accessories/Accessory-Design-Gui... (particularly fascinating to page through for the diagrams alone, including iPhone XS, AirPods and Apple Watch Lug Assembly...)

Yes, it is really bad.

The "new" docs are just generated API docs with very little to no content.

I seldom do macOS/iOS nowadays, but like many I am forced to dive into the deprecated docs every time I want to read anything meaningful.

The little to no content is exactly right! I'll find an API, and click on a method, and all it sends me too is the method definition. No description about the what to send it and what it does.

This is so true and so maddening. I'm trying to learn this stuff, and there are so many things that just aren't documented, or documented in random obscure/dumb places. Does Apple really not care at all?

It's been awhile since I've worked outside the Apple ecosystem, but when I first started with Mac programming I thought their documentation was absolutely amazing.

I wasn't combing through the bottoms of experts-exchange posts to find obscure references to long forgotten Microsoft C++ APIs, I could just read the docs for the class and do what I wanted.

In the decade or so I've been writing mostly Mac/iOS software, this experience is largely unchanged and still better than other platforms I've tried to write for.

I think everyone looks at their own favorite platform through rose colored glasses and it's pretty easy to dismiss the warts when you've dealt with them for so long.

Yes it's terrible, it's like they've just given up. I started just at the beginning of the OS X era and the documentation was already much less good than the classic "Inside Mac" stuff, but they did at least attempt to keep it up to date for a while. But over the last ten years it seems to have got a lot worse.

I don't do so much low level Windows stuff but my perception is that the quality has dropped off significantly there, too; I remember local installs of MSDN being really complete and easy to use, but last time I looked online they seemed to have moved away from that and it was just a mess of broken links and missing info.

Now try to get certificates / “provisioning profiles” / “app capabilities” running, but with any configuration slightly out of the ordinary. You’ll want to rather shoot yourself.

Is this Craig Federighi's fault? Ever since Tim Cook combined the Software team under one umbrella things hasn't gotten any better.

And there is worst. Corrupted iCloud Photos and Video Syncing.


> And there is worst. Corrupted iCloud Photos and Video Syncing.

Countering that with my own anecdata - I've had iCloud Photos turned on since it was released in the dev builds with ~85k photos and videos using 305GB and haven't had a single instance of this happen.

(It sucks that it happened to him, of course.)

It happened to me once with a Corrupted iCloud Backup, I was lucky to have a local iTunes Backup on my Mac.

I know this may sound hash, stupid or naive.

I don't want to know there is only less than 10% Chance of a keyboard failure within 1 year. ( As if that number is any good at all ) For keyboard I want it to be below 1% within its 5 years.

I don't want to know there is 0.01% of Photo / Video Corruption. Even at that percentage there is nearly 2M iCloud users at risk. For my photos, my memories, it needs to be perfect. If that requires doubling the price of iCloud Storage then so be it.

The whole reason I use iCloud was because my last 2 NAS has file corruption and some photo were either filtered with green or had bottom half gone. Later I had to buy a Synology NAS with BTRFS ( I wish they had used ZFS ). It was way too much hassle.

Yes I know you need to do offsite backup etc, but that is like telling average Joe to install drivers themselves on their new Linux computer. No ones wants to do that.

How did you determine that none of the 85k photos were corrupt? I have a much smaller library and I didn't think anything was corrupt until one day I was looking for a photo and it was all black. I knew the photo was not supposed to be all black.

A fair question! I suppose I should say "in my experience of taking my photos and browsing them over the last N years, I haven't encountered a single one that's corrupt."

Honestly I don't know who owns developer relations/tech docs. Could be Craig.

Could be Phil Schiller, who has owned the app stores since 2015. That might explain why developer.apple.com has turned into more of an information-lite marketing site than an actual resource.

God forbid, it could be Eddy Cue.

A couple weeks back I was going through Safari’s release notes. They put them all on one page [1] and none of the sections have IDs so I can’t link to them directly. WTF.

[1] https://developer.apple.com/safari/technology-preview/releas...

These are actually Safari Technology Preview's release notes. They're also published on the WebKit blog [0] which is a much better source since it has separate posts for each release and it includes links to the associate commits of each change. Their other posts are also generally superb and well worth checking out!

With that being said, I think your criticisms are completely reasonable and valid. Instead of duplicating this info they should just provide links to the WebKit blog.

[0] https://webkit.org/blog/

Thanks for pointing out. The break-out blog posts on WebKit do seem to be high-quality.

They have IDs so you can directly link to a section:


Fair enough that each section that represents a version has IDs. I was referring to the sections within each version, such as the "Web Inspector" version for v68.

It took me forever to figure out that APFS didn't support arbitrary Unicode but rather only assigned codepoints in a fixed Unicode spec...(I was writing a fuzzing app)

> APFS doesn’t allow files to be created with filenames that contain unassigned codepoints in the Unicode 9.0 standard, whereas HFS+ does.

This is from a "legacy" document: https://developer.apple.com/library/archive/documentation/Fi...

It's definitely still the case on the office Macs that we bought last year.

I have a hard time seeing how open sourcing their documentation could not be the answer here.

Apple, the control freak company, open sourcing its documentation? :))))

Take a look at their Github page and you might be surprised :) Worked wonders for Swift.

Yeah, but Swift was meant to be an open source project from day 1. The Apple GUIs are part of the secret sauce from their point of view, they probably won't ever be open source... I imagine not even the documentation.

They removed the man pages a while back and broke so many links. It just seems punitive and petty.

apple are no longer developer friendly, so why should they provide documentation. look at their pro-summer laptops. and arcane policies on iOS development

A couple weeks ago an automatic Mac OS update removed my (I presume, symlinked-) /usr/include directory. I use CLion not XCode, so this move broke my build, through no fault of my own, with little to go on as to what suddenly had gone wrong. A possible fix would be to install the commandline developer tools, except those were already installed and the installer refuses to run again to repair it.

This is a specific example of a regular occurrence; the details differ each time. I compare developing a personal project on Mac OS to be like getting cut off and run off the road by a luxury SUV: "Did you do that because you didn't know I was there, or did you do that deliberately?"

The question I have to ask myself repeatedly about consumer technology is “what does the manufacturer expect ‘normal people’ to do?” Anytime I’m confronted with moving a video from my computer to a relative’s iPhone or trying to load music from a cloud service into Apple Music/iTunes, I ask myself this and usually just conclude that normal users would give up and I do too. Then I crawl back over to my desktop (running OpenBSD) and pretend to cry.

My sister-in-law asked me to rip a cd so she could play some lullabies for her son. I did. Then she asked me how to copy them to her iphone. I could not figure out a way to do it. So I turned the thing into a static html page with <audio> tags so she could play it. This seems comically user unfriendly, or maybe even hostile from a company that's supposed to "just work".


I honestly don't remember whether I tried iTunes, but it sucks either way. Either I tried and couldn't figure it out. Or maybe that's the only way to do it and I didn't try it? Which means you need some heavy proprietary software to copy a file. Every non-Apple mp3 player or smart phone that I've ever seen lets you use standard protocols to just move media around without setting up user accounts or synchronization settings or god knows what.

Just fyi: easy up-/download options via USB have been degenerated on Linux as well. MTP (which Google pushed to replace mass storage device mode) is hit-and-miss on Ubuntu; for example, it doesn't work with S8 and newer at all. MicroSD doesn't work with newer/larger cards, Bluetooth is a clusterfuck ... in many ways, the last decade has been a desaster for interfaces people care about.

I remember ~10 years ago i used Automator with Folder actions (or something called like that) to setup automatic resize and transfer of videos from a folder to my iPod Touch through iTunes, so my guess is that iTunes would do the trick. Unless they broke it since then.

For future reference, you can download VLC from app store, it has a local wifi server which you can connect to from pc and upload media files from browser.

iTunes has been the only way to do it since the iPhone was released.

Have you tried /usr/local ?

That is where you're supposed to install user libraries/header files.

Apple "owns" the system paths no different to every other vendor.

The way I treated this on Linux is that /usr is packages installed by the package manager and /usr/local is where ad-hoc compiled (./configure && make install) software goes.

I always assumed this from --prefix=/usr/local being the default in autotools.

From wikipedia: (Historically and strictly according to the standard, /usr/local is for data that must be stored on the local host (as opposed to /usr, which may be mounted across a network). Most of the time /usr/local is used for installing software/data that are not part of the standard operating system distribution (in such case, /usr would only contain software/data that are part of the standard operating system distribution). It is possible that the FHS standard may in the future be changed to reflect this de facto convention.)

All of /usr/ is protected by SIP except for /usr/local/. Even if you have SIP off (I do too), it's worth glancing at what directories are protected, as it gives pretty clear insight into where Apple expects users to put stuff.

Sure but I ran an out-of-the-box CLion with out-of-the-box CMake, compiled a popular open source project that in theory is cross platform compatible with Mac, and it fails in a C standard library header deep inside Apple's headers after a chain of "#include_next" because it didn't find "/usr/include". Is this a fault of mine, Jetbrains, Kitware, or Apple?

> A possible fix would be to install the commandline developer tools, except those were already installed and the installer refuses to run again to repair it.

Apple’s command line tools ships with a package containing these headers, which you can find at /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg. Note that this package is only a temporary workaround (to fix issues like yours) and you should migrate to using your toolchain’s include path.

Right I eventually found that out (and temporarily fixed it by making a symlink manually). My question about fixing it right is (1) How? and (2) How am I expected to know this? Because: I'm using an out-of-the-box CLion with it's out-of-the-box CMake, and I thought this is exactly the sort of SNAFU that CMake is supposed to handle? Does the fault lie with JetBrains, Kitware, Apple?

Compared to amazon developer docs and twillio apples can hold its own.

We should call this something, DocRot?

Tim Cook, cooking books?

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