1. 25

  2. 8

    Such a shame. Apple inherited phenomenal documentation from OPENSTEP. When I started with Cocoa, it was still OpenStep with a few convenience functions and without Display PostScript (I don’t think CoreGraphics was a public API back then, all drawing was via NSBezierPath) and with KVC / KVO added. Going from knowing nothing to writing a 900-page book about Mac development was really, really easy (though helped by implementing a bunch of the Apple APIs in GNUstep). The KVO documentation wasn’t great and the Bindings stuff that they built on top was a mess (great idea, horrible developer experience: stuff either worked perfectly or failed for completely opaque reasons). I didn’t really understand who bought books about OS X development because the docs were great: a mixture of high-level overviews and detailed API docs.

    Their docs have become steadily worse since those days. I suspect that’s partly the loss of Steve Jobs’ influence. Back in the NeXT era, he was a big advocate of clean and well-documented API design.

    1. 2

      Usually I wouldn’t strongly disagree with your example (inheriting from openstep) but when exactly was that? I suppose before OSX launched? That makes it 1999ish?

      So nope, if it deteriorates in a few years where you’d think mostly the same people are there, it’s a good point. But after over 20 years? How many of the code would still be there? It’s long enough that just by pure chance I’d say this has nothing in common with that anymore. Also Apple is much too big to claim any “but it was good at one point, in this (narrow or not) scope of openstep.

      1. 4

        It’s over a decade now since I was writing Cocoa / GNUstep things on a regular basis, but it wasn’t just the inherited docs that were good. My first Mac ran OS X 10.2, when AppKit and Foundation were still OpenStep with a few extensions. Even back then, the docs had clearly been updated from OpenStep. I remember PDFKit and libdispatch, in particular, both having good docs around the 10.6 era (2009), so they were still releasing new well-documented frameworks post-NeXT. PDFKit was introduced in 10.4, libdispatch in 10.6. I think 10.6 was when they introduced the ‘modern’ Objective-C runtime and at that point their runtime API docs were much better than the NeXT-era ones (with detail on how to use the low-level APIs for reflection).

        Some of the stuff inherited from Classic MacOS was very badly documented. I remember QuickTime being completely incomprehensible.

        A few things started going downhill around this time too. I think it was QuickLook that chose to implement the plugin infrastructure in terms of COM interfaces. Apple didn’t ship a compiler with any COM helper support so the skeleton project required you to manually set up COM vtables, GUIDs, and so on. This was incredibly poorly documented and was presumably caused by the fact that the Objective-C runtime couldn’t do library unloading at that point. This was definitely an outlier though. I looked at some Apple docs for the first time in ages a couple of months ago and was pretty shocked. In core GUI classes, they had parameters that took an enumerated type that had no documentation for what the values meant. Some of the methods had no docs at all other than a single sentence the basically restated the method name.

        A lot of things gradually got worse as NeXT people left. Once Steve Naroff left the compiler team, they were left without anyone working on the toolchain who actually understood what had made Objective-C good in the first place. Their UIs got shiny things from the very first release, but most of them were at least neutral from a usability standpoint, some were actually good (for example, when you have a window-modal dialog box, making it a sheet that appears from the top of the window makes it visually clear that the dialog is the reason that this window isn’t responding to events).

        It’s worth noting that there was quite a lot of internal conflict at Apple between the old Mac folks and the old NeXT folks. The NeXT folks mostly won in the end but things like CoreFoundation and a bunch of the CF-based APIs (such as the Keychain) were driven by the other camp. The OS X Finder was originally written in C with Carbon because the NeXT camp couldn’t convince the rest of the platform to build a core part of the UI on top of the NeXT GUI system.

        It’s probably also relevant that when OS X launched there was basically no existing Objective-C software. A bunch of OpenStep apps were ported, but that was a tiny number in absolute terms. Apple provided Cocoa (Objective-C), Carbon (C) and Mocha (Java) in the hope that at least one of them would become popular. The teams working on them had a huge incentive to write good docs because it was clear quite early on that the ones that didn’t get significant amounts of developer mindshare would be killed off and poor documentation is a great way of driving devs to a different API. Objective-C probably had more of an up-hill struggle in these early years because there were vastly more C or Java programmers who would naturally gravitate to Carbon or Mocha than to Cocoa, so they had a massive incentive to provide good docs for Cocoa. It’s probably not a coincidence that the docs started to go downhill shortly after they announced that the Java bridge and Carbon were both going away (Carbon never made the 64-bit switch and so stayed around as a 32-bit-only dead end for a while, I think Java was killed earlier).

        1. 3

          There was conflict (I was there at the time, 1998-2007) but not as bad as you make it out to be. From my viewpoint it had pretty much subsided by the time 10.0 shipped. CoreFoundation wasn’t something partisan, it was the necessary refactoring that allowed Carbon and Cocoa (and more generally C and Obj-C) to coexist.

          Apple had some great developer docs in the pre-NeXT days. There were entire books describing how to use individual technologies. (QuickTime docs sucked, but IMHO that’s because QT itself was a nightmare of an API.)

          In my experience the engineering teams did work with docs teams to some degree in the OS X era, though less closely than earlier. (When I worked on AppleScript and OpenDoc there were doc writers embedded in engineering, going to our meetings.) I don’t know what’s happened since. I really don’t think this is something you can attribute to Steve’s passing; I never saw any evidence he was involved in that at all. He cared about shiny lickable pixels above all else.

          I still develop for Apple platforms, but mostly at a low level where they just look like Unix. When I do some higher level work I often get horribly frustrated by current docs. The only real overview of CloudKit hasn’t been updated since 2014, has no Swift code, and shows deprecated APIs. There is vital knowledge about it that’s literally only available from WWDC session videos from four or five years ago.

          I’m used to bad docs, but usually it’s on open source software where I can dig into the implementation to elucidate it. If Apple is going to keep their code closed, they need to be held to a much higher bar.