19 ms·

The State of Apple's Developer Documentation

371 points by bangonkeyboard 7y ago

dzonga 7y ago
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 7y ago
  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?"
  - snazz 7y ago
    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.
    - recursive 7y ago
      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".
      - saagarjha 7y ago
        iTunes?
        recursive 7y ago
        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.
        tannhaeuser 7y ago
        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.
        Crinus 7y ago
        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.
        empath75 7y ago
        iTunes has been the only way to do it since the iPhone was released.
        iaml 7y ago
        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.
  - threeseed 7y ago
    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 7y ago
      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 7y ago
        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.
    - phaedrus 7y ago
      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?
  - saagarjha 7y ago
    > 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.
    - phaedrus 7y ago
      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?
natch 7y ago
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 7y ago
  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.
  - Austin_Conlon 7y ago
    I'd been trying to find https://developer.apple.com/videos/archive/ https://developer.apple.com/videos/archive/ for a while, thanks.
  - natch 7y ago
    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.
Klonoar 7y ago
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 7y ago
  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 7y ago
    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...
    - Klonoar 7y ago
      > 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.
hombre_fatal 7y ago
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.
- Klonoar 7y ago
  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.
- povertyworld 7y ago
  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 7y ago
    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.
protomyth 7y ago
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 7y ago
  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".
  - DaiPlusPlus 7y ago
    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.
  - ASalazarMX 7y ago
    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/rzasd/sc092508.pdf https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rza... [2] https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rzasc/sc092507.pdf https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rza...
    - 7y ago
kaycebasques 7y ago
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/release-notes/ https://developer.apple.com/safari/technology-preview/releas...
- threeseed 7y ago
  They have IDs so you can directly link to a section: https://developer.apple.com/safari/technology-preview/release-notes/#r68 https://developer.apple.com/safari/technology-preview/releas...
  - kaycebasques 7y ago
    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.
- TheAceOfHearts 7y ago
  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 7y ago
    Thanks for pointing out. The break-out blog posts on WebKit do seem to be high-quality.
gumby 7y ago
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 7y ago
  > 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.
  - gumby 7y ago
    Yeah, I didn’t mean to excuse them!
  - jonhendry18 7y ago
    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.
- addicted 7y ago
  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.
js2 7y ago
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/Cocoa/Conceptual/Archiving/Archiving.html 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/nskeyedarchiver?language=objc 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?
- layoutIfNeeded 7y ago
  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.
  - wool_gather 7y ago
    There's also an awful lot of important information tucked away in WWDC videos, unfortunately.
  - jonhendry18 7y ago
    But will that continue to be the case as headerless Swift takes over?
    - layoutIfNeeded 7y ago
      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.
- mantap 7y ago
  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.
tialys 7y ago
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 7y ago
  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 7y ago
    This query displays nothing, for me - just the link to /xcode/ on their site.
    - saagarjha 7y ago
      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?
paultopia 7y ago
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?
olliej 7y ago
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 7y ago
  I file reports in Bug Reporter about outdated Swift docs, and they always fix it and respond back.
  - olliej 7y ago
    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 :-/
thrower123 7y ago
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.
- simion314 7y ago
  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.
  - lsiebert 7y ago
    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."
- wbl 7y ago
  BSD man pages. When you didn't have the Internet you depended on good docs.
  - saagarjha 7y ago
    Apple's BSD man pages are pretty out of date, ironically…
- Crinus 7y ago
  > 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.
- muststopmyths 7y ago
  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.
commandlinefan 7y ago
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 7y ago
  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.
  - pjmlp 7y ago
    That was my introduction to OOP, Turbo Pascal and later Turbo C++ manuals.
  - jonhendry18 7y ago
    I would plop down and read the fat volumes of the NeXTSTEP General Reference.
- jeroenhd 7y ago
  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
- Crinus 7y ago
  > 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.
dnautics 7y ago
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 7y ago
  > 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/FileManagement/Conceptual/APFS_Guide/FAQ/FAQ.html https://developer.apple.com/library/archive/documentation/Fi...
  - dnautics 7y ago
    It's definitely still the case on the office Macs that we bought last year.
userbinator 7y ago
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 7y ago
  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 7y ago
    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 7y ago
      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 7y ago
        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).
jarjoura 7y ago
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 7y ago
  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.
- Someone 7y ago
  ”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.
gnachman 7y ago
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/+/d40e271ac1613cea1a24eac3cca6efe173cd0696/Source/WebKit/chromium/src/mac/WebInputEventFactory.mm 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.
- Klonoar 7y ago
  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.
  - helge5 7y ago
    It is mentioned a few times, but never w/ any reference or explanation :-) Could someone please provide some pointers on this?
    - Klonoar 7y ago
tomcam 7y ago
At least they make up for those deficiencies by selling state of the art laptops for well under $5000 if you’re willing to shop carefully and give up a few key features. For example, I only spent $4400 for a laptop that has at least 80% of the keys working most of the time. Fortunately I only had to wait three days to take it in and have the extended service warranty fix rejected.
makecheck 7y ago
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).
- saagarjha 7y ago
  > 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 :(
  - maxxxxx 7y ago
    That’s how modern design works. MS is using the same tech of broken links and empty pages.
    - lstamour 7y ago
      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 ...
      - maxxxxx 7y ago
        “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:)
- 7y ago
the_gipsy 7y ago
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.
fit2rule 7y ago
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 7y ago
  "Whatever is done to the platform, it must accommodate the strategy of capture of developer mindset." Only if the company has a clue.
brador 7y ago
We should call this something, DocRot?
pjmlp 7y ago
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 7y ago
  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.
jlarcombe 7y ago
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.
mannberg 7y ago
I have a hard time seeing how open sourcing their documentation could not be the answer here.
- oblio 7y ago
  Apple, the control freak company, open sourcing its documentation? :))))
  - mannberg 7y ago
    Take a look at their Github page and you might be surprised :) Worked wonders for Swift.
    - oblio 7y ago
      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 7y ago
They removed the man pages a while back and broke so many links. It just seems punitive and petty.
ksec 7y ago
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-syncing/ https://mjtsai.com/blog/2019/05/20/beware-icloud-video-synci...
- zimpenfish 7y ago
  > 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.)
  - ksec 7y ago
    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.
  - kccqzy 7y ago
    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.
JohnAtCC 7y ago
Tim Cook, cooking books?
RandallBrown 7y ago
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.
norswap 7y ago
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.
- deleted 7y ago
  [deleted]
- wool_gather 7y ago
  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 7y ago
    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...
brian_herman__ 7y ago
Compared to amazon developer docs and twillio apples can hold its own.

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 7y ago
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?"
- snazz 7y ago
  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.
  - recursive 7y ago
    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".
    - saagarjha 7y ago
      iTunes?
      - recursive 7y ago
        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.
        tannhaeuser 7y ago
        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.
        Crinus 7y ago
        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.
        empath75 7y ago
        iTunes has been the only way to do it since the iPhone was released.
        iaml 7y ago
        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.
- threeseed 7y ago
  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 7y ago
    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 7y ago
      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.
  - phaedrus 7y ago
    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?
- saagarjha 7y ago
  > 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.
  - phaedrus 7y ago
    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?

natch 7y ago

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 7y ago
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.
- Austin_Conlon 7y ago
  I'd been trying to find https://developer.apple.com/videos/archive/ https://developer.apple.com/videos/archive/ for a while, thanks.
- natch 7y ago
  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.

Klonoar 7y ago

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 7y ago
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 7y ago
  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...
  - Klonoar 7y ago
    > 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.

hombre_fatal 7y ago

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.

Klonoar 7y ago
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.
povertyworld 7y ago
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 7y ago
  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.

protomyth 7y ago

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 7y ago
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".
- DaiPlusPlus 7y ago
  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.
- ASalazarMX 7y ago
  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/rzasd/sc092508.pdf https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rza... [2] https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rzasc/sc092507.pdf https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rza...
  - 7y ago

kaycebasques 7y ago

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

threeseed 7y ago
They have IDs so you can directly link to a section: https://developer.apple.com/safari/technology-preview/release-notes/#r68 https://developer.apple.com/safari/technology-preview/releas...
- kaycebasques 7y ago
  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.
TheAceOfHearts 7y ago
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 7y ago
  Thanks for pointing out. The break-out blog posts on WebKit do seem to be high-quality.

gumby 7y ago

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 7y ago
> 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.
- gumby 7y ago
  Yeah, I didn’t mean to excuse them!
- jonhendry18 7y ago
  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.
addicted 7y ago
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.

js2 7y ago

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/Cocoa/Conceptual/Archiving/Archiving.html 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/nskeyedarchiver?language=objc 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?

layoutIfNeeded 7y ago
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.
- wool_gather 7y ago
  There's also an awful lot of important information tucked away in WWDC videos, unfortunately.
- jonhendry18 7y ago
  But will that continue to be the case as headerless Swift takes over?
  - layoutIfNeeded 7y ago
    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.
mantap 7y ago
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.

tialys 7y ago

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 7y ago
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 7y ago
  This query displays nothing, for me - just the link to /xcode/ on their site.
  - saagarjha 7y ago
    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?

paultopia 7y ago

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?

olliej 7y ago

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 7y ago
I file reports in Bug Reporter about outdated Swift docs, and they always fix it and respond back.
- olliej 7y ago
  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 :-/

thrower123 7y ago

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.

simion314 7y ago
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.
- lsiebert 7y ago
  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."
wbl 7y ago
BSD man pages. When you didn't have the Internet you depended on good docs.
- saagarjha 7y ago
  Apple's BSD man pages are pretty out of date, ironically…
Crinus 7y ago
> 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.
muststopmyths 7y ago
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.

commandlinefan 7y ago

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 7y ago
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.
- pjmlp 7y ago
  That was my introduction to OOP, Turbo Pascal and later Turbo C++ manuals.
- jonhendry18 7y ago
  I would plop down and read the fat volumes of the NeXTSTEP General Reference.
jeroenhd 7y ago
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
Crinus 7y ago
> 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.

dnautics 7y ago

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 7y ago
> 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/FileManagement/Conceptual/APFS_Guide/FAQ/FAQ.html https://developer.apple.com/library/archive/documentation/Fi...
- dnautics 7y ago
  It's definitely still the case on the office Macs that we bought last year.

userbinator 7y ago

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 7y ago
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 7y ago
  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 7y ago
    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 7y ago
      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).

jarjoura 7y ago

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 7y ago
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.
Someone 7y ago
”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.

gnachman 7y ago

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/+/d40e271ac1613cea1a24eac3cca6efe173cd0696/Source/WebKit/chromium/src/mac/WebInputEventFactory.mm 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.

Klonoar 7y ago
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.
- helge5 7y ago
  It is mentioned a few times, but never w/ any reference or explanation :-) Could someone please provide some pointers on this?
  - Klonoar 7y ago

tomcam 7y ago

At least they make up for those deficiencies by selling state of the art laptops for well under $5000 if you’re willing to shop carefully and give up a few key features. For example, I only spent $4400 for a laptop that has at least 80% of the keys working most of the time. Fortunately I only had to wait three days to take it in and have the extended service warranty fix rejected.

makecheck 7y ago

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

saagarjha 7y ago
> 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 :(
- maxxxxx 7y ago
  That’s how modern design works. MS is using the same tech of broken links and empty pages.
  - lstamour 7y ago
    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 ...
    - maxxxxx 7y ago
      “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:)
7y ago

the_gipsy 7y ago

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.

fit2rule 7y ago

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 7y ago
"Whatever is done to the platform, it must accommodate the strategy of capture of developer mindset." Only if the company has a clue.

brador 7y ago

We should call this something, DocRot?

pjmlp 7y ago

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

jlarcombe 7y ago

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.

mannberg 7y ago

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

oblio 7y ago
Apple, the control freak company, open sourcing its documentation? :))))
- mannberg 7y ago
  Take a look at their Github page and you might be surprised :) Worked wonders for Swift.
  - oblio 7y ago
    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 7y ago

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

ksec 7y ago

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-syncing/ https://mjtsai.com/blog/2019/05/20/beware-icloud-video-synci...

zimpenfish 7y ago
> 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.)
- ksec 7y ago
  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.
- kccqzy 7y ago
  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.

JohnAtCC 7y ago

Tim Cook, cooking books?

RandallBrown 7y ago

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.

norswap 7y ago

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.

deleted 7y ago
[deleted]
wool_gather 7y ago
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 7y ago
  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...

brian_herman__ 7y ago

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