The State of Apple's Developer Documentation
mjtsai.com
mjtsai.com
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...
https://en.wikipedia.org/wiki/Cartesian_coordinate_system
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.
Anyone who did middle school math knows it's Cartesian. ;P
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.
Forever be damned the heretics at asciiwwdc.com!
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...
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.
That's a pretty low bar. None amazing desktop UI I've seen has been non-native.
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.
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...
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.
Check the PWA and what is coming to the Web talks.
One reason less to bother with Electron.
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.
Yes, PWAs have different levels of access to host APIs.
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 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.
The one of developers that want to get payed, but refuse to pay for their tools?
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.
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.
https://github.com/microsoft/microsoft-ui-xaml/blob/master/d...
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".
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.)
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.
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.
...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.
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.
It's crazy.
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.
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.
...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.
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:
https://developer.apple.com/library/archive/technotes/tn2083...
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.
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
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".
[0]https://developer.apple.com/documentation/foundation/nsexcep...
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
Exactly.
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.
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.
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.
Old timers may not realize how far it's fallen/not kept up.
I learned what good developer documentation could be from it!
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.
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.
That vastly more critical Facetime/facepalm issue certainly went straight to /dev/null , so ... thanks for the laugh, I guess.
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.
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 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…
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.
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.
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.
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.
I remember I did a double take when I saw Corbin answering questions about NSTableView on StackOverflow, felt like hell had frozen over.
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
http://www.microsoft.com/en-us/download/details.aspx?id=2095...
(Best to get a copy while you still can...)
https://docs.microsoft.com/en-us/dotnet/api/system.threading...
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
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.
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.
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).
Not only can you not do this, Apple's own site search doesn't bring them up. They just get lost :(
Let’s hope MS won’t incorporate this “feature” in the race to make their docs worse:)
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...
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.
https://developer.apple.com/library/archive/documentation/Co...
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:
https://developer.apple.com/documentation/foundation/nskeyed...
Apple docs used to be great. They've become pretty awful. Has Apple even published a tech note in years?
Thankfully the headerdocs are still mostly intact.
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.
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.
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.
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.
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)
And:
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.
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.
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?
[1] https://developer.apple.com/videos/all-videos/
[2] https://developer.apple.com/videos/wwdc2012/
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
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.
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.
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.
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)
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.
So frustrating, even with my background.
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.
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 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.
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.
Of course, having any documentation is better than none...
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.
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.
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.
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.
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.
Because you can create a PDF from anything e.g. web pages by going to Print, selecting PDF dropdown and "Save as PDF".
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.
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...
https://support.apple.com/en_AU/manuals/
Not all in PDF but most.
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...)
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.
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.
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.
And there is worst. Corrupted iCloud Photos and Video Syncing.
https://mjtsai.com/blog/2019/05/20/beware-icloud-video-synci...
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.)
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.
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.
[1] https://developer.apple.com/safari/technology-preview/releas...
https://developer.apple.com/safari/technology-preview/releas...
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.
This is from a "legacy" document: https://developer.apple.com/library/archive/documentation/Fi...
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?"
That is where you're supposed to install user libraries/header files.
Apple "owns" the system paths no different to every other vendor.
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.)
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.
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.
Only if the company has a clue.