Become a fan of Slashdot on Facebook

 


Forgot your password?
Close
typodupeerror
×
Programming Apple

Apple, Your Developer Documentation Is Garbage (chriskrycho.com) 95

Posted by msmash from the closer-look dept.
Software developer Chris Krycho writes: Over the past few months, I have been trying to get up to speed on the Apple developer ecosystem, as part of working on my rewrite project. This means I have been learning Swift (again), SwiftUI, and (barely) the iOS and macOS APIs. It has been terrible. The number of parts of this ecosystem which are entirely undocumented is frankly shocking to me. Some context: I have spent the last five years working very actively in the JavaScript front-end application development world, working in first AngularJS and then Ember.js. Ember's docs once had a reputation of being pretty bad, but in the ~4 years I've been working with it, they've gone from decent to really good. On the other hand, when I was working in AngularJS 5 years ago, I often threw up my hands in quiet despair at the utter lack of explanation (or, occasionally, the inane explanations) of core concepts. I thought that would have to be the absolute worst a massive tech company (in that case, Google) providing public apis could possibly do. I was wrong.

The current state of Apple's software documentation is the worst I've ever seen for any framework anywhere. Swift itself is relatively well covered (courtesy of the well-written and well-maintained book). But that's where the good news ends. Most of SwiftUI is entirely undocumented -- not even a single line explanation of what a given type or modifier does. Swift Package Manager has okay docs, but finding out the limits of what it can or can't do from the official docs is difficult to impossible; I got my ground truth from Stack Overflow questions. I've repeatedly been reduced to searching through WWDC video transcripts to figure out where someone says something relevant to whatever I'm working on. Several people have complained in recent years that Apple's documentation is often incomplete or missing altogether. A developer has tried to figure out. Accidental Tech Podcast, a popular podcast that talks about Apple's ecosystem, discussed the issue in a recent episode.
This discussion has been archived. No new comments can be posted.

Apple, Your Developer Documentation Is Garbage More

Apple, Your Developer Documentation Is Garbage

Comments Filter:

  • Microsoft: "Developers Developers Developers!"

    Apple: "You're developing wrong..."

  • Who cares (Score:2, Insightful)

    by 110010001000 ( 697113 )

    Developing for platform-specific closed ecosystems is a mistake in the first place. You shouldn't do it.

    • Re:Who cares (Score:5, Funny)

      by TFlan91 ( 2615727 ) on Monday October 28, 2019 @12:40PM (#59355110)

      Especially if it's a bloated, overpriced market with gullible customers. That's a business mans worst nightmare.

    • And yet systems like z/OS tend to have very extensive documentation. Apple has no excuses here.
      • It's not an accident. Apple does this on purpose to corral consumers and their money. In this case, the developers themselves are the consumers.

        • ...In this case, the developers themselves are the consumers.

          Yeah - this makes sense. It's a shame that Apple doesn't apply the same logic as OpenBSD whereas on OpenBSD, finding incorrect/missing documentation is treated as a bug and attempts to remedy it (when they can).

    • It's a big enough chunk of the market you'll want to grab as an app developer. So you use a cross platform development tool. There's a few that hide the platform specifics, but they are pretty limited in what you can do with them. And there's more versatile tools (Xamarin etc), but in that case you still need to deal with some platform-specific stuff, which means you'll need documentation.

      The article is right though, Apple documentation is seriously lacking in some cases.

    • Re: (Score:1)

      by Anonymous Coward

      Developing for platform-specific closed ecosystems is a mistake in the first place. You shouldn't do it.

      Then let's make a new one [xkcd.com]! Brilliant!

      • Misapplication of an xkcd comic. The idea is to develop for existing, open standards, rather than a closed one. Of course that doesn't leave you much room since, in the mobile world, there are no existing, open standards. You can develop for Android or iOS. That's about it.

    • Sure, I'll go tell my boss that. I'm sure it will be well-received when he tells the CTO that.
    • Depends on your goals. A lot of people are in it to put food on the table, and for them, developing for iOS makes sense: it's a huge market that doesn't seem to have problems with spending.

      If you have other goals, it might be a mistake. From a consumer standpoint, I absolutely loathe iOS. I have an iPad at home and the one thing I want to do with it (emulators) Apple has a policy against (which means I can't easily do it because closed ecosystem). But from a business perspective, I think there's a good r

      • Re: (Score:3)

        by laird ( 2705 )

        The irony is that Apple was the first company to produce thorough, readable developer documentation, in the early MacOS days. It just got more and more complicated as they layered on more and more generations of os/SDK.

        If you want to sell software, iOS is the biggest market. So while as a developer you might not like it, it's where businesses launch products, since that's where most of the paying customers are, and it has lower support costs compared to the highly fragmented Android market.

        That being said,

        • The irony is that Apple was the first company to produce thorough, readable developer documentation, in the early MacOS days. It just got more and more complicated as they layered on more and more generations of os/SDK.

          Yah, no, that is simply not true. I was there. Apple was highly selective about what they documented, bordering on abuse. When I contacted Apple for missing hardware details I was rudely told, in essence, to mind my own business. That was just a few months after the Macintosh came out. I quit developing for Apple right then, and never touched it again.

          From where I sit, Apple today is precisely the same Apple as 35 years ago.

  • The Price of Constant Change (Score:3)

    by alvinrod ( 889928 ) on Monday October 28, 2019 @12:38PM (#59355090)
    I suspect that a large part of this is because Apple is continually changing all of this around and there's very little stability in the APIs or language (how many times has Swift undergone some updates that break some aspect of programs in older versions now?) which means no one really wants to take the time to produce documentation because they know it's going to be useless in a year if not a few months down the road.

    For all the gripes against languages like C or Java, they're pretty well documented and you can find a lot of good example code to illustrate some of the quirks or other unexpected behaviors of the language. Normally I'd say to choose a language appropriate for the project and its needs, but when you want to play in Apple's ecosystem then they're the ones that get to dictate how the game is to be played. But if you're an Apple developer you should be used to that by now.

    • To be honest, in the 35+ years I've worked on software and firmware, documentation has always been substandard or non existent. The source is the documentation may sound like a joke but it's the common practice. Even in professional products you will find gaps because the docs are assuming the common case and they haven't gotten around to find grained details yet.

      Worst case, also very common, the documentation disagrees with the actual product. That for both internal and third party commercial paid suppor

    • Re: (Score:2)

      by _xeno_ ( 155264 )

      It's not just that. I mean, it is that, but it's not just that.

      Apple has two major problems with their documentation right now that cause a lot of their APIs to be undocumented:

      1. They relatively recently updated their documentation system but have not moved everything over to the new documentation system. A lot of documentation is currently "archival" and technically several versions out of date.
      2. A lot of the Objective-C APIs are well documented, but the Swift wrappers, which don't always use the same na

    • Nope. It's 100% because they're not spending enough on documentation. They have all of the money, but apparently zero fucks.

      Documentation is not optional. Whether you're talking about comments, or actual user-facing docs, they are a crucial part of software.

      • Clearly, that's wishful thinking, drinkypoo. Apple is still doing fine...so it's optional in some conditions. The devs will still develop because that's where a big chunk of money is...they willingly enslave themselves and some actually like the barriers to entry for competing developers. Not nice, and not as it should be - but as it IS.

        • I think this Catalina wine killer action is going to put a big dent in their user base... And thus, developer interest. No doubt that's why they recently took steps to let you put iOS apps on OSX. But tablet apps are not going to fill the gap left by real apps going away.

    • Yeah, the problem of stable well documented products is that they tend to become standard, de facto public domain and thus, outside the control of their creators.

      They definitely want to avoid that and this is the result.

    • While Balmer was the one that went off screaming developers, Jobs actually did a great job of giving them the tools they needed.

      Macintosh Human Interface Guidelines [acm.org] still is, IMHO, a gold standard (that Apple themselves have started to ignore).

      OS X shipping with a fully working, free, development stack was unheard of at the time.

      Jobs seemed to understand that people making the software were the ones that built things, keep them happy then focus on the end users. Cook has gone all in on milking the end user

      • "While Balmer was the one that went off screaming developers, Jobs actually did a great job of giving them the tools they needed."

        Inconsistent and incorrect documentation, you mean? That wasn't what they needed.

        "Macintosh Human Interface Guidelines still is, IMHO, a gold standard (that Apple themselves have started to ignore)."

        Started? Over a decade ago they had three different GUI toolsets just for their own apps, that all looked different.

        "OS X shipping with a fully working, free, development stack was un

        • Two things.
          - Maybe Xcode wasn't on the disk, but it came out at the same time and you didn't
          have to user CodeWarrior any more.

          - I remember the couple (or more) of phone-book thick NeXT documentation volumes.
          That wouldn't have happened without Job's blessing and funding.

          • All of the NeXT owners I knew were quite happy. But Apple is not NeXT, and OSX is not NeXTStep. And I've seen plenty of people complain about Apple's lack of commitment to useful, correct docs.

      • The "pro" lines have wilted under Cook.

        ORLY?

        https://www.apple.com/mac-pro/ [apple.com]

    • I suspect that a large part of this is because Apple is continually changing all of this around and there's very little stability in the APIs or language

      That would be one way of spinning it, however it really seems like Apple just doesn't care about developer docs, they care a lot more about emojies.

  • Yes, much garbage, often.

  • I use Flutter because of this (Score:3)

    by cliffjumper222 ( 229876 ) on Monday October 28, 2019 @12:40PM (#59355104)

    I want to develop apps for Android and iOS and so I was looking for a framework that offered that. Google's Flutter works best for me. It abstracts the iOS crap and enables me to focus on the code. I still have to deal with XCode for a few tasks but I never program in Swift. The docs are pretty good and Dart makes sense.

    • What kind of a performance hit does your code take on iOS versus development with Apple's toolset?

  • The current state of Apple's software documentation is the worst I've ever seen for any framework anywhere.

    You have clearly not taken a look at many software frameworks if you think Apple's docs suck more balls that all other bad software documentation combined. On another note, I know clicks are money but this laser focus on clickbait for Apple haters is making them wear out their mouse buttons with frightening speed and worse yet, many of them are developing serious osteoarthritis in their clicking finger.

    • You perhaps want more lying pro-apple stories to get off on. Sorry they are few and far between for apple. As a company they are shit.

      • You perhaps want more lying pro-apple stories to get off on. Sorry they are few and far between for apple. As a company they are shit.

        Easy to proclaim.

        Not so easy to prove.

      • You perhaps want more lying pro-apple stories to get off on. Sorry they are few and far between for apple. As a company they are shit.

        Ohhh, the hate is strong in this one. Do any of the hate masters out there need an apprentice?

    • Re: (Score:2)

      by suutar ( 1860506 )

      who said combined?

      • who said combined?

        C'mon, in the mind of an Apple hater, can an Apple product possibly suck less than everything else of its kind that sucks combined?? It's implicit in everything they say.

    • I know clicks are money but this laser focus on clickbait for Apple haters is making them wear out their mouse buttons with frightening speed and worse yet, many of them are developing serious osteoarthritis in their clicking finger.

      Stellar!

  • Everyone's documentation is garbage. Everyone's too busy working on the product, rather than the documentation.

    • Everyone's documentation is garbage. Everyone's too busy working on the product, rather than the documentation.

      That's too harsh. Don Knuth has championed "Literate programming" since the 1980s. Check it out.

      • Ahh, that's interesting, thank you!

        However this "literate programming" would help other programmers, but not the company overall. Documentation isn't just for programmers - someone has to run the code and understand all of it's intended functionality. Remember that wherever there's code being written, there's generally a support staff that has to understand code changes, and be able to explain changes to clients.

        • When writing anything, you have to keep your audience in mind. When I document my code, the intended reader is a person, perhaps my future self, who wishes to understand the code so he can modify it. I have never written code that I expected to be supported by a support staff, but if I did I would first get to know the support staff so I could document my code in the way that would be best for them.

          Explaining changes to clients is very different. The closest I have come to doing that was when I was worki

          • In my experience, that kind of documentation is written by professional writers, in collaboration with the developers.

            See, now you're just bragging. ;)

            But seriously, your experience isn't the norm ...in Alabama.

  • Welcome to the new normal. Yeah the API is open source but we don't bother to do any documentation. "Use that bitches!"

    • I used to work for an unnamed Israeli company. lets just say they had 80% of the market for their niche. The company used a convoluted version of C with so many macros that noone reading it would recognize it as C. it also had a very detailed and complicated build system to the extent we almost never wrote code directly rather we set various different rules and flags and code would be generated.
      Now our company used to sell the license and customization projects almost at cost or sometimes even at a loss. Th

      • I used to work for an unnamed Israeli company. lets just say they had 80% of the market for their niche. The company used a convoluted version of C with so many macros that noone reading it would recognize it as C. it also had a very detailed and complicated build system to the extent we almost never wrote code directly rather we set various different rules and flags and code would be generated. Now our company used to sell the license and customization projects almost at cost or sometimes even at a loss. The ideas was to make it up on maintenance where our services division would charge huge billing rates. Clients knew about the billing rates and many insisted that they would only sign a deal if we hand over the code so they could maintain it themselves. We did handover the source code to many clients but never the build system and other dev tools. Very few client were able to maintain it themselves and would come back to us for maintenance. Open Source is all fine and good but it is only useful when its readable.

        By the standards of Free Software, if you don't also hand over the build system, you aren't providing the source code. The GPL is explicit about this.

  • Anyone else remember the Inside Macintosh Toolbox series of books?
    An entire hardback volume dedicated to a single API in Classic MacOS, each ranging from a small hundred pages up to many hundreds.

    *sigh* I miss old Apple, and worse is just how long ago that was.

    • Anyone else remember the Inside Macintosh Toolbox series of books?
      An entire hardback volume dedicated to a single API in Classic MacOS, each ranging from a small hundred pages up to many hundreds.

      *sigh* I miss old Apple, and worse is just how long ago that was.

      Yeah, back when it cost $500/yr to be a Registered Apple Developer, and you had to submit a business prospectus, a DUNS number and a sample of your DNA to become Registered.

      Those were the days, alright...

      • Re: (Score:2)

        by dissy ( 172727 )

        Yea I don't think you were born yet "back in those days" if you think 10 years ago was the 1980's

  • Who actually has decent documentation nowadays? (Score:4, Insightful)

    by rnturn ( 11092 ) on Monday October 28, 2019 @12:46PM (#59355150)
    Vendor-written documentation dried up when they figured out they could milk their customers with expensive training courses on how to use the software they sold. A huge amount of Open Source software documentation is pretty damned lacking, too. Makes you long for the days of the Grey (or Blue or Orange or White) Walls.

    • 300$ nodejs certifications are another way, i'm sure apple will have their own version if they dont already

  • Chronically understaffed (Score:1)

    by Anonymous Coward

    As someone who used to work on that team a few years back, I felt a fair amount of schadenfreude when I read this. DevPubs (or whatever their name is this week) is chronically badly understaffed. The result is that they can't document everything. That wasn't necessarily a show-stopper in the early says, but when iOS came out, things got a lot worse, because there were the same number of people documenting two platforms instead of one. As of when I left, the number of added employees still wasn't anywher

    • My retirement plan is to offer to work remote for Apple half time, just updating dev documentation. If they just had a few really seasoned developers doing that, they could have some really polished documentation pretty rapidly I think.

      • No wonder you have you head up apples ass here all the time. Trying to secure your retirement plan.

        • No wonder you have you head up apples ass here all the time. Trying to secure your retirement plan.

          And that, folks, is a prime example of the grammar capabilities of the average Apple-Hating Slashtard!

          Good show!

      • If they just had a few really seasoned developers doing that, they could have some really polished documentation pretty rapidly I think.

        They need really seasoned developers, but technical writing is a special skillset that most developers don't have. That's why it's a documentation team that works well.

        Apple has nearly a trillion dollars - they could have the best documentation in the industry if they wanted to. There must be a reason they don't want to. Perhaps it's guild status like CCNE's or MCSE's u

  • Wrong - SwiftUI is lacking, rest of docs good (Score:5, Informative)

    by SuperKendall ( 25149 ) on Monday October 28, 2019 @01:00PM (#59355212)

    I was really puzzled when I read this, as Apple has some of the better SDK documentation I've found across a lot of systems.

    But reading the summary, the whole issue is really with *SwiftUI*. Yeah that is totally new, and evolving rapidly (I like adopting new technologies and even I am waiting for a while to adopt this). Docs for that take a while to get to a decent place, from anyone...

    But even there if you look around there are a LOT of people working furiously producing SwiftUI content that update things all the time.

    • I'm a full time Swift developer an I completely agree with this article.

      At the end of the day, when you're vending an api, it isn't done until it's documented. Full stop.

    • Re: (Score:2)

      by _xeno_ ( 155264 )

      Yeah, no, the source article may have been about SwiftUI, but it's not just SwiftUI. Huge portions of Foundation remain entirely undocumented for the Swift version (which wouldn't matter if the Swift APIs mapped 1:1 with the Objective-C APIs, but they don't), and large parts of UIKit are just not documented within Swift.

      Worse, a lot of the documentation points to documents that no longer exist or are now "archived" and no longer refer to the current version of the API. (They may or may not still be correct.

  • "I have spent the last five years working very actively in the JavaScript front-end application development world"
    I mean, yech. It's not a strongly-typed language.

    That said, there is something to this. Microsoft's developer documentation steals Apple's lunch money on this one.

  • SwiftUI requires the latest version of iOS to function at all... anyone writing real apps with it today is really limiting their app. Check back in a year or two when the install base of viable devices is 80-90% and the documentation is finished(Apple is still incrementing on SwiftUI pretty hard)

    • Check back in a year or two when the install base of viable devices is 80-90% and the documentation is finished(Apple is still incrementing on SwiftUI pretty hard)

      That's pathetic. Apple used to have one of the best documentation groups in the industry (Sun was good too) and their developer docs were beautifully-produced and comprehensive, ready to go with (and often ahead of) every release, broken down into each subsystem, usually with sample code in both C and Pascal. Several gigabytes of code and docs w

  • Xcode has got to be the worst IDE I've ever used. It's buggy and its UI is just fucking retarded. They really need to follow the lead of JetBrains there.
  • I always cringe when people say you must document everything, document before you even code, make ten million words of documentation before you know what to code, then document all your code as you write it so if you have to change it you have to change the documentation.

    Sure, in my case it's not really necessary to go overboard on the documentation for commercial projects where there's an expectation of mainly relying on not making a tangled web of messy code instead and where people are expected to be

  • The documentation used to be amazing, but it's definitely been going downhill. From burying sample code on the developer website, to the number of new APIs that have no description beyond their function name. Thankfully Stack Exchange is full of people who have helpfully reverse engineered how most things work.

    To top it off, it really feels like no one at Apple is actually using Xcode's built-in documentation browser. The documentation window has fairly obvious problems like.. it causes Xcode to crash every

  • One of the Agile Manifesto's core tenets is, "working software over comprehensive documentation". Mixed with the rest of the manifesto, you get a definition of "working" that no respecting engineer would agree to and piss poor documentation when you try to fix it.

    • Re: (Score:2)

      by Pyramid ( 57001 )

      Individuals and interactions over processes and tools --make sure people's emotions are minded

      Working software over comprehensive documentation -- get it out the door, screw the poor sap who has to use or fix it

      Customer collaboration over contract negotiation -- ensure scope creep and spaghetti code are de rigueur

      Responding to change over following a plan -- start your journey before deciding where the destination is and change course often without deciding if it's the right direction.

  • Same shit different day (Score:5, Insightful)

    by byteherder ( 722785 ) on Monday October 28, 2019 @03:02PM (#59355734)
    You must be a noob around here. If you saw Microsoft's developer documentation in the '80s and '90s, you would think you have now died and gone to heaven. There wasn't Stack Overflow or Youtube videos to ask questions or show you how it's done. You had to figure it out on your own. Furthermore, it wasn't just that there were parts that were undocumented, parts that were documented had significant bugs in them.

    Welcome to the world of software development.

    • In the mid-90s, they used to send a quarterly plastic box full of CDs to the developers
      (developers, developers, developers..)

      Nothing was more thrilling than booting Bulgarian NT4.0 beta7.34 on my 386.

      • I loved those mailers. Grab the MSDN Docs CDs and do full install locally. Then browse & dream :)

    • If you want that kind of excitement nowadays, try Google Cloud's documentation :) Some parts are excellent, some parts are just not there which makes debugging issues a challenge, especially since the error messages often are very generic making it almost impossible to filter down to good hits on Google or SO.

  • I wrote relevant programming books (Score:4, Informative)

    by EMB Numbers ( 934125 ) on Monday October 28, 2019 @05:25PM (#59356362)

    I am the author of "OpenGL ES for iOS" and co-author of "Cocoa Design Patterns" and "Cocoa Programming". The complaint about Apple's documentation goes all the way back to NeXT's documentation in 1988.

    Cocoa and Cocoa Touch frameworks cannot be understood well as a collection of parts. It is necessary to understand a dozen or so interrelated design patterns to understand the frameworks. You cannot take the design patterns a-la-cart. They are not really optional.

    25 years ago, the comp.sys.next news group was full of statements like "NeXT's documentation sucks. Why can't I just do ..." and "...it feels like the frameworks are fighting me at every turn..." The reason, IMHO, for such comments is that if you are unaware of the design patterns being used, the frameworks absolutely fight you. From NeXT/Apple's point of view, there is a right way to do things and every other way is wrong. The frameworks intentionally fight "wrong" approaches.

    Once you understand and can identify the recurring design patterns, Cocoa and Cocoa Touch almost don't need documentation. You can guess the class and method names. One aspect that NeXT/Apple has implemented brilliantly is naming consistency. I can identify a hand full of grating examples of poor/inconsistent naming, but they are very rare.

    There are a few data points:

    - Apple has "Hidden" all of the decades of code samples at https://developer.apple.com/li... [apple.com]
    - SwiftUI is brand new, and as far as I can tell, Apple doesn't even use it much yet.
    - SwiftUI is "intuitive" if you have decades of experience with NeXT/Apple's naming conventions. If you know the conventions, you don't need documentation to tell you the names of things. Documentation is still needed though :)
    - Cocoa's design patterns originated with Objective-C, and there are some mismatches when using Swift. The Swift ways of doing things are sometimes antithetical to the historic Cocoa ways of doing things.
    - Cocoa is generally elegant in design and implementations. It was a trail blazer. Much of it shipped commercially in October 1988. Having said that, modern Javascript frameworks are mostly very elegant. I've been learning Javascript React as a side project, and I am generally impressed by it.
    - Developing with Cocoa is IMHO vastly more pleasant that developing with Android frameworks. Just compare designs for Tables and related classes sometime. Sigh.

  • When OSX was young, the documentation was at least as good or better than Inside Macintosh.
    NeXT had published docs as thick as phone books and Apple inherited that initiative.
    Say what you will about Jobs, NeXT wouldn't have done that without his (and Avie's) push.

    When it settled down and Richard Kerris was in charge of Apple Dev Services, it improved even
    more. Indexed HTML with sample code expressly written to help the developer.
    Sure, it was the $500 club back then, but software wasn't 99 cents a pop either

    • AR will be or possibly even already is the next great advance in computing. But i sincerely doubt that Apple will be the one to popularize it. Everything they do comes at a price premium, and AR is already quite expensive to carry off well when the hardware cost is considered. It's also not Apple's style to lead, they prefer to refine. Then again, they've done precious little of THAT lately...

      Almost no matter what I am doing, I can think of ways for AR to improve it. But I can't think of anything that would

  • Apple has had shitty documentation at least as early as I wrote code on a Powerbook in 1995:
    Even though they advocated using C, there was practically nothing documented - not only that, but most functionality wasn't written in C! I could barely find the list of Pascal function names, let alone their parameters, let alone how you were meant to call them from C.

    My god, when I started programming C++ in BeOS I was in heaven!!

Slashdot Top Deals

If all else fails, lower your standards.

Close