1. 32

  2. 23

    The craziest thing I discovered from the inside is that there are gigantic swathes of fundamentally critical technology that lack even internal documentation. It was a regular occurrence that I’d have to ping the people who wrote some important bit of the media pipeline to get an annotated header or even just a couple of hours of explanation.

    ETA: I got considerably more assistance from tab completing method names in PyObj-C than I did from official documentation sources. It was insane.

    1. 7

      Note that I updated the title in response to some comments on that other website, because it was misleading the discussion. Ended up being a hotter take than I actually intended!

      1. 6

        I wonder if Apple has a blind spot here, because they have a “Documentation team”, but that team shifted focus to documentation presentation. The website UI and JavaScript framework keeps changing for the sake of changing, but nobody seems to be writing and maintaining the prose.

        Let’s not forget that not only function documentation is dying, but also (once) incredibly valuable Technical Notes all talk about Mac OS X Leopard as the latest thing.

        1. 7

          I am not sure what this article adds. It’s a rant, but there are no concrete examples of bad documentation, no examples of Apple documentation that is well-done, no examples of what you were concretely trying to archieve and how the Apple documentations fails there. This could be a nice analysis, bit I didn’t learn much beyond the title (except that apparently Ember.js documentation is good and Rust policy requires documentation of every symbol).

          1. 6

            This stack overflow thread of sample Apple Watch code which hasn’t worked basically ever is an excellent example https://stackoverflow.com/questions/46086536/apple-sample-code-for-watchkit-extension-background-refresh

          2. 4

            Not at all involved with apple stuff, but I found https://nooverviewavailable.com/ a neat idea (via https://atp.fm/episodes/349 )

            1. 3

              Yes! I meant to include that in a footnote in the post! Editing it in now; thanks for the reminder!