
The State of Apple's Developer Documentation - bangonkeyboard
https://mjtsai.com/blog/2019/05/20/the-state-of-apples-developer-documentation/
======
Klonoar
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...

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

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

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

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

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

------
gnachman
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...](https://chromium.googlesource.com/chromium/blink/+/d40e271ac1613cea1a24eac3cca6efe173cd0696/Source/WebKit/chromium/src/mac/WebInputEventFactory.mm)

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.

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

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

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

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

------
hombre_fatal
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/](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.

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

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

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

~~~
saagarjha
Insufficient pushback from developers?

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

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

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

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

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

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

~~~
Klonoar
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-...](https://www.corbinstreehouse.com/blog/2019/03/the-sad-state-of-
logging-bugs-for-apple/?cat_id=86&order=DESC)

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.

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

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

~~~
saagarjha
> 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…

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

~~~
lstamour
Good news, you can find Inside Macintosh online (via Google) and in
[https://developer.apple.com/library/archive/documentation/ma...](https://developer.apple.com/library/archive/documentation/mac/pdf/MacintoshToolboxEssentials.pdf)
(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...](https://developer.apple.com/library/archive/documentation/mac/pdf/MoreMacintoshToolbox.pdf)
(More Macintosh Toolbox) and
[https://developer.apple.com/library/archive/documentation/ma...](https://developer.apple.com/library/archive/documentation/mac/pdf/ImagingWithQuickDraw.pdf)
(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/](https://docs.swift.org/swift-book/) (and in Apple Books store) or the
CarPlay guide? [https://developer.apple.com/carplay/documentation/CarPlay-
Na...](https://developer.apple.com/carplay/documentation/CarPlay-Navigation-
App-Programming-Guide.pdf) I do kind of miss when guides were more complete,
such as the Automator Programming Guide
[http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.693...](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.693.6773&rep=rep1&type=pdf)
(It appears it was removed in 2016 from developer.apple.com)

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

------
tialys
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/](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](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.

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

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

~~~
saagarjha
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?

------
js2
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:

[https://developer.apple.com/library/archive/documentation/Co...](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Archiving.html)

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...](https://developer.apple.com/documentation/foundation/nskeyedarchiver?language=objc)

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

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

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

~~~
wool_gather
> also higher-level conceptual documents around various topics

Yes! The _FOO Programming Guide_ s and _BAR Reference_ s 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.

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

~~~
lstamour
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/](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/](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/wwdc2012)
[https://developer.apple.com/videos/wwdc2013](https://developer.apple.com/videos/wwdc2013)
[https://developer.apple.com/videos/wwdc2014](https://developer.apple.com/videos/wwdc2014)
[https://developer.apple.com/videos/wwdc2015](https://developer.apple.com/videos/wwdc2015)
[https://developer.apple.com/videos/wwdc2016](https://developer.apple.com/videos/wwdc2016)
[https://developer.apple.com/videos/wwdc2017](https://developer.apple.com/videos/wwdc2017)
[https://developer.apple.com/videos/wwdc2018](https://developer.apple.com/videos/wwdc2018)

I really wish these were easier to find, still.

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

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

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

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

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

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

Only if the company has a clue.

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

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

~~~
olliej
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 :-/

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

~~~
bangonkeyboard
_> 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.

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

------
norswap
Writing good documentation is super hard.

I try to do it for my parser
([https://github.com/norswap/autumn4/](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.

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

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

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

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

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

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

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

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

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

~~~
ASalazarMX
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...](https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rzasd/sc092508.pdf)

[2]
[https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rza...](https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rzasc/sc092507.pdf)

~~~
threeseed
Actually they do:

[https://support.apple.com/en_AU/manuals/](https://support.apple.com/en_AU/manuals/)

Not all in PDF but most.

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

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

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

------
paultopia
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?

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

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

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

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

[https://mjtsai.com/blog/2019/05/20/beware-icloud-video-
synci...](https://mjtsai.com/blog/2019/05/20/beware-icloud-video-syncing/)

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

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

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

------
kaycebasques
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...](https://developer.apple.com/safari/technology-
preview/release-notes/)

~~~
TheAceOfHearts
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/](https://webkit.org/blog/)

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

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

~~~
saagarjha
> 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...](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/APFS_Guide/FAQ/FAQ.html)

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

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

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

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

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

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

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

~~~
phaedrus
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?"

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

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

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

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

------
brador
We should call this something, DocRot?

------
JohnAtCC
Tim Cook, cooking books?

