A concrete example of what goes wrong with Apple's docs

Original Article ↗ Hacker News Discussion ↗

Apple’s official documentation for macOS and iOS APIs is widely criticized as shallow, incomplete, and hard to navigate, especially for newer frameworks like SwiftUI. Developers describe wasting hours on basic tasks, relying instead on LLMs, third‑party blogs, and archived “old Apple” docs that were far more thorough, and some argue this is a consequence of Apple’s yearly release cycle, internal secrecy, and low prioritization of technical writing. Others counter that the APIs are usable if you understand object-oriented patterns and read carefully, but there is broad concern that poor docs hurt productivity and are pushing developers toward AI-assisted tooling and alternative platforms with better documentation.

LLMs as Workaround for Apple Docs

  • Many commenters say ChatGPT and similar tools are now their primary way to learn Apple APIs, especially SwiftUI, macOS, and iOS frameworks.
  • LLMs are praised for quickly surfacing patterns, edge-case tricks, and missing examples that Apple’s docs don’t provide.
  • Some note limitations for proprietary/internal codebases where security prevents pasting code into LLMs; enterprise-focused tools are mentioned as a potential solution.

Current State of Apple Documentation

  • Widely perceived as sparse, example-poor, and often omitting critical behavioral details (e.g., networking headers, UIPickerView behavior, table/stack views).
  • Docs frequently push important knowledge into WWDC videos, which many find an unacceptable reference format, especially as older videos disappear.
  • Some say SwiftUI docs and tutorials are “wonderful” by Apple standards, but still incomplete for non‑happy‑path use cases.

Historical Decline and Causes (as discussed)

  • Several recall that older Objective‑C / Cocoa docs and “Inside Macintosh”–era materials were exemplary, with deep conceptual explanations and examples.
  • The decline is attributed in-thread to: yearly OS release cadence, Swift/Objective‑C dual tracks, lack of dedicated technical writers, and leadership not prioritizing documentation quality.
  • Others argue scaling doc teams is nontrivial: good doc writers must be strong developers, are hard to hire, and often undervalued and underpaid.

API Design, OOP, and Discoverability

  • Complaints about “needlessly overcomplicated” OOP designs and deep inheritance (e.g., NSOpenPanel inheriting from NSSavePanel, UIKit components), which make behavior non-obvious without traversing class hierarchies.
  • Some contend this is a user problem: anyone using an OO framework should expect to navigate inheritance via IDE and parent classes.
  • Others counter that good docs should surface inherited behavior, provide examples, and teach concepts rather than assuming prior platform knowledge.

Docs vs. LLM Future

  • One camp argues traditional, comprehensive human-written reference docs are still essential (citing Go’s standard library as a positive model).
  • Another predicts documentation will shift toward tutorials and LLM-accessible annotations, with LLMs generating answers instead of humans writing exhaustive references.
  • There is concern that as LLMs “suffice,” the incentive to invest in high-quality official documentation will further weaken.

Platform Comparisons and Exit Decisions

  • Some find Apple still better than Windows or Android; others say poor docs and complex APIs pushed them away from native Apple development entirely.
  • Flutter’s documentation is held up as a strong counterexample with clearer cross‑platform APIs and better reference material.