4 ms·

> Apple's documentations [sic] is famously dreadful. The irony is that Apple's documentation used to be excellent, and if you look in the "Documentation Archiv

• matwood 3y ago
  Yeah. The Objc docs for coding Mac and early iOS apps was quite good. I used it extensively.
• jorvi 3y ago
  I weep when I read their older HIG for macOS and then see in the current day how hard they violate so many of the principles and lessons they laid down there.
  • deleted 3y ago
    [deleted]
• silvestrov 3y ago
  The "Inside Macintosh" series from 1985 was a masterpiece of documentation. It was a bliss to read. Check the updated docs for "The Standard File Package" which is the UI for selecting files. Page 3-4 (all page numbers has section number). It has full description of the UI, keyboard shortcuts, data structures and example code. It even includes how to customize the dialog. There is 69 pages of documentation of just how to select a file! https://vintageapple.org/inside_r/pdf/Files_1992.pdf https://vintageapple.org/inside_r/pdf/Files_1992.pdf Apple no longer understands that good docs is a competitive advantage. The web has such good docs at developer.mozilla.org that it is a world apart.
  • mschuster91 3y ago
    > Apple no longer understands that good docs is a competitive advantage. Apple's competitive advantage is the rock-solid, durable hardware (compared to what's considered "acceptable" in the Windows world) and the lock-in effect of things like the App Store and its customer base, iMessage and Find My. Apple doesn't need to attract developers any more, and so the documentation gets little love.
    • musicale 3y ago
      > Apple doesn't need to attract developers any more Maybe not, but I have found that better documentation helps me write better, more reliable software with less time wasted on trial and error and fruitless internet searches.
      • mschuster91 3y ago
        Me as well, but Apple doesn't need to take care about that.
    • etse 3y ago
      Well put. Unfortunately true!
  • musicale 3y ago
    Surely they can afford to hire a few good technical writers, right? Presumably SwiftUI should also be easier to write code for than the classic Mac toolbox?
• plorkyeran 3y ago
  When I got into iOS development (about a decade ago now) I was absolute blown away by how good Apple's documentation was. It was accessible to someone unfamiliar with their platform, well written, and covered everything from the high level to low level details. Sadly that seems to have also been the exact moment that they fired everyone working on documentation.
  • CoastalCoder 3y ago
    > Sadly that seems to have also been the exact moment that they fired everyone working on documentation. Out of curiosity, when was that?
• js2 3y ago
  Case in point, here's the archived documentation on how to use Open and Save Panels, with example code: https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/UsingtheOpenandSavePanels/UsingtheOpenandSavePanels.html https://developer.apple.com/library/archive/documentation/Fi... (Third link when searching DDG for "NSSavePanel example".)
• CoastalCoder 3y ago
  > First, the yearly OS release schedule, which began in 2012 on the Mac, didn't leave enough time to write documentation. I'd think this problem could be partly solved with money, i.e. hiring more writers. Even if the docs had to lag the OS release by a few months, I still suspect the fundamental reason is: > Third, Tim Cook and Craig Federighi just don't give a crap about quality.
  • lapcat 3y ago
    > I'd think this problem could be partly solved with money, i.e. hiring more writers. That's classic Mythical Man-Month thinking.
    • russelg 3y ago
      Sure that applies to software development, but does it really apply to writing documentation? The articles currently on the developer page could be split up evenly between a team and be worked on simultaneously.
      • lapcat 3y ago
        Writing documentation requires communication and collaboration with engineering. As you add people to an organization, you also add meetings, bureaucracy, and various other encumbrances. Not to mention that the technology to be documented needs to be done or done-ish, which is difficult when you're shipping major updates yearly! Besides, how large do you think the talent pool is of good documentation writers? I would estimate that it's actually harder to find good technical doc writers than it is to find good programmers. 1) The minimum qualifications for a good API doc writer is practical experience programming with the technology to be documented. That already narrows the field significantly. You can't just a hire a comp sci grad straight out of college. 2) Indeed, a comp sci grad straight out college probably wouldn't want the job anyway. A lot of people aspire to be programmers, because it seems cool, fun, and has excellent compensation. Not many people aspire to become doc writers as a career. 3) The compensation for doc writers is generally lower than for programmers, so if you're already an experienced programmer per 1, then why would you take a step down? 4) The natural retort is going to be, "Just pay doc writers more!" But that's not going to work for several reasons. First, the programmers will be unhappy if the doc writers are paid more than them. Second, companies don't value doc writers as much. Third, once you get off the programmer career track and write docs, it can be difficult or impossible to get back on the programmer career track if you ever want or need to leave Apple. In general, the market is not huge or lucrative. What you tend to get for documentation writers, then, is often older programmers who are starting to experience age discrimination, finding it harder to get a programming job, so they settle for writing API documentation. But that's not a huge pool of available workers.