[HN Gopher] A concrete example of what goes wrong with Apple's docs
___________________________________________________________________
A concrete example of what goes wrong with Apple's docs
Author : imbnwa
Score : 97 points
Date : 2024-01-07 20:16 UTC (2 hours ago)
(HTM) web link (www.amimetic.co.uk)
(TXT) w3m dump (www.amimetic.co.uk)
| jitl wrote:
| For Mac desktop programming and Swift in general, I find ChatGPT
| quite helpful. It's been quite good at dredging up the kind of
| "one weird trick" I tend to need to work with these kind of
| closed source framework that you can't truly understand. I don't
| think I'll ever get used to Apple stuff since I'm so used to
| being able to go-to-source of frameworks in
| Java/Ruby/Android/Go/C/Javascript programming but ChatGPT at
| least keeps me unstuck.
|
| At least SwiftUI gives you a very nice paved road of
| productivity. Again if you need something off the beaten path
| good luck, but it's never been easier to make app-shaped tools
| for Apple platforms.
| eurekin wrote:
| I'm dreaming of the day there would be a chatgpt like thing for
| all those internal proprietary tools and their "documentation"
| jitl wrote:
| What's the difference you're imagining from today's ChatGPT?
| eurekin wrote:
| ChatGPT knows nothing of those libraries and their code. I
| can't paste anything into context, because of security
| reasons :)
| jitl wrote:
| Ah I understand now. I have my eye on SourceGraph's Cody
| AI, they're working on an enterprise version, although
| it's TBD how locked down it will be:
| https://sourcegraph.com/cody
| asimpson wrote:
| My experience as well. While I'd love a proper go to source
| approach, chatGPT nails most of the issues I run into with
| SwiftUI.
| allenu wrote:
| ChatGPT has been a godsend for helping me figure out how to use
| quite a few Mac and iOS APIs in the last year. There are APIs
| that would've taken me an hour or more to work out how to use
| by searching online, experimenting, digging up old WWDC videos
| (often the only place to really learn how to use a given API
| properly), but now it takes seconds of ChatGPT. It's been a
| game-changer.
| peterbmarks wrote:
| I went through pretty much the same dance yesterday trying to
| figure out the right way to choose a directory in my SwiftUI app.
| SwiftUI is a wonderful UI toolkit but it's far from complete. The
| documentation Apple is creating for it is wonderful, check out:
| https://developer.apple.com/tutorials/swiftui
| lukeh wrote:
| It's a pity when you consider how detailed Inside Macintosh was.
| madsbuch wrote:
| It might be a hot take, but I think documentation is mostly
| obsolete. Nobody wants to write it, and nobody wants to read it.
|
| How the future works is probably:
|
| 1. Tutorials / case specific guides 2. documentation-annotated
| code base read by an LLM to yield answers to questions.
|
| Already now, the most popular open source projects seem to
| prioritise guides for common use cases over extensive
| documentation.
| jaggederest wrote:
| I'm pretty sure both of those count as documentation.
|
| https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...
|
| I think you mean something a bit more specific, maybe
| "comprehensive reference documentation written by humans",
| though I'm not sure codebase annotations get away from that.
| jitl wrote:
| I disagree. Golang and its standard library are terrifically
| productive for me because they have plain old high quality
| module documentation on every public struct and function. Of
| course you need a few tutorials to introduce people to a
| library's main use cases but after building that initial
| familiarity I find the kind of docs Go has to be the most
| useful for me. A doc browser like Dash (Mac) or Zeal (open
| source) that makes search lightning fast multiplies the
| helpfulness of that kind of docs.
| Karellen wrote:
| > nobody wants to read [documentation].
|
| OP wants to read documentation. It's in the article.
|
| Quite a few commenters say that they're resorting to LLMs, not
| because that's how they want to learn about the code they're
| using, but _because_ the documentation is terrible and LLMs
| summarising snippets from dozens of different forum questions
| and blog posts is the only alternative they have to terrible
| documentation.
|
| > most popular open source projects seem to prioritise guides
| for common use cases over extensive documentation.
|
| Open source projects that people aren't being paid to work on
| probably don't have extensive documentation, because writing
| extensive documentation is hard, and the kinds of people who
| like hacking on code that solves their problems are probably
| not people who enjoy writing extensive documentation when they
| could be implementing another feature. Even if a large segment
| of their users would prefer that, and it's what would be best
| for the project.
| otterley wrote:
| I won't merge any PRs to my open source projects without a
| corresponding documentation change. I think it's a good rule
| that everyone should follow as it benefits both the user and
| the project's other developers.
| pasc1878 wrote:
| And that is why it is difficult to learn new things.
|
| I want to read documentation but then I have been programming
| for 45 years and am used to reasonable documentation.
|
| If you are not experienced in language X the being told to look
| at its source code to see what and how it works is not good as
| the reason you are asking is because you don't yet understand
| X. Documentation has to be written assuming you don't know what
| is happening.
|
| Even UNIX/Emacs documentation is frustrating as if you know
| Unix/Emacs than searching will give the information you need
| but if you have not user that port before then the
| documentation is opaque.
|
| I suspect that documentation works when it is written by a
| separate team than the developers of the product and the
| documenters use the product.
| ToucanLoucan wrote:
| Will absolutely cosign this. So many of Apple's components for
| both iOS and MacOS development are dreadfully over-complicated
| and the documentation if anything, makes it worse with no
| examples provided, no use cases, nothing. And of course is
| subject to change at the whim's of Apple's engineers.
|
| So often as a developer I end up just creating a single-line
| static wrapper function that does something that interfaces with
| Apple code, then call that instead. Things like a share sheet are
| incredibly complicated for seemingly little if any actual need.
| Example: I have a static wrapper function for sharing that
| accepts the following parameters:
|
| - The View Controller to present the share sheet from
|
| - The originating view/button that it should be presented from
| (on iPad)
|
| - The URL of the file
|
| - A subject and message, either one, both or neither, appropriate
| to the share
|
| And that's it. Five pieces of information. Inside that function
| I:
|
| - Load the data from the file into a Data object, and confirm the
| URL is good
|
| - Save a second copy of the file to the file system with the
| appropriate name I'd like it to show the user
|
| - Convert the "Any" object passed into the button (view, button,
| bar button item, etc.) as a set of coordinates from which to
| spawn the popover, because Apple's code does not do this reliably
|
| - Instantiate a Share Sheet Subject Body Provider, which is an
| object you have to provide the share sheet which contains... 2
| strings
|
| - Instantiate a UIActivityViewController, which is a subclass of
| View Controller using the subject/body provider and the URL to
| the file copy I created as the arguments for that
|
| - Set the source view of that controller to an arbitrary View
| I've placed that's just the coordinates from earlier, with a
| height and width of 1, placed onto the view controller
|
| - UNLESS it's a bar button item, in which case I set the bar
| button item property to _that_ and skip the coordinates
| altogether
|
| - Then I present this view controller on the origin view
| controller
|
| And I'm sorry, I'm willing to grant that _some_ of this
| complexity is down to engineering concerns I 'm not aware of, or
| taking into account things I've never done. But holy. Shit. What
| a process to go through. To simply share a file as Apple intends,
| I need a class that is fifty lines of code, and a second class of
| another 20-ish lines, to provide subject and body. Which again, I
| cannot stress this enough, is TWO. STRINGS.
|
| SURELY. SURELY SOMEHOW we could make this easier.
| tiffanyh wrote:
| Don't forget, one of the things you get for the $99/year
| developer fee is documentation.
|
| https://developer.apple.com/support/compare-memberships/
| srajabi wrote:
| Does this mean you get additional documentation then the
| example in the blog? Or is that $99 for the bad documentation?
| chedabob wrote:
| No, it's the same documentation.
|
| I think even for the new APIs added in non-public betas, it's
| all on the main website now.
|
| Also there's docs that aren't on the dev.apple site for
| things like Apple Pay, but it's not a perk of paying $99 a
| year. I suspect the actual hardware docs for the Vision
| headset are private too (they were for the Apple Silicon
| DTK).
| jitl wrote:
| As far as I know, all the docs are free and don't require
| logging in to view.
|
| The only hit for the word "documentation" on the linked page is
| this paragraph which explicitly says you don't need to pay to
| learn:
|
| > You can learn how to develop apps for Apple platforms for
| free without enrolling. With just an Apple ID, you can access
| Xcode, software downloads, documentation, sample code, forums,
| and Feedback Assistant, as well as test your apps on devices.
| jackblemming wrote:
| Apple and Android mobile development both have some of the worst
| APIs and designs I've ever seen. I really can't believe these
| companies have the most talented developers based on their
| objective output. I think at best, they have a small handful of
| incredibly smart devs and the rest may as well be leetcode
| monkeys.
| realusername wrote:
| That's because there's no competition, you are building an app?
| Then you need both an iOS and an Android version, no matter
| what. Their docs can be as broken as they want, you still have
| to target the duopoly.
| mdhb wrote:
| That's starting to change now where you have things like
| Flutter which get you native cross platform apps with
| excellent documentation https://docs.flutter.dev/
| bowsamic wrote:
| The worst part is not only that the documentation is awful but
| that Apple uses needlessly overcomplicated OOP design on top.
| It's just a bad experience all around. I don't think SwiftUI is
| any better either, though it avoids the old OOP mess it is still
| very complicated and if you want to do anything not immediately
| supplied by the library you often are best falling back to AppKit
| anyway. It's just very unpleasant programming in general
| kalleboo wrote:
| SwiftUI started out really simple but now that they're
| extending it to cover more functionality it's getting more and
| more complicated. Instead of complicated OOP design now it's
| inscrutable functional design, now with the bonus of Swift's
| "less verbose" syntax and naming.
|
| I was dealing with TransferRepresentation the other day and
| this API must be extremely confusing to someone who's new to
| Swift. The documentation reads like you're supposed to already
| be familiar with some concept that is never explained.
| simonw wrote:
| I'd love to understand WHY Apple's documentation is so
| notoriously weak.
|
| One guess: maybe it's related to their culture of internal
| secrecy? If a team works on a project for years without anyone
| outside of that team having any visibility of it, writing
| comprehensive documentation is presumably a lot less valuable -
| at least while it's under development.
| jitl wrote:
| It's gotten worse over the years. The new Swift stuff tends to
| be cursory, but I frequently hit "archived" legacy docs that
| are super well written and go in depth on whole systems
| (although it's now 10 years out of date). My favorite bit of
| technical writing is the old text system docs:
| https://developer.apple.com/library/archive/documentation/Te...
|
| My hypothesis is that in the old days, technical writers on
| teams would lead the docs effort, but today's culture may have
| many teams with only developers, and those developers are
| primarily interested in shipping code, not docs.
| hoc wrote:
| Thanks for that comment.
|
| That weird "relaxed" notation that Swift brought to Apple's
| current doc format/structure made it so frustrating if you just
| want to use a certain thing without capturing the whole
| framework.
|
| In 2024 you better have some scratch paper at hand to make notes
| when browsing Apple Swift docs...
| politician wrote:
| Launch HN: Hi everyone, I'm politician, and I'm happy to launch a
| new service called AppleDocs.ai. We use generative AI to make
| Apple developer documentation useful, since Apple has completely
| dropped the ball on this area. Pricing starts at $8/mo for
| individuals.
|
| /satire, but only barely -- upvote if you want this to exist!
| popcalc wrote:
| The LLM would be a gimmick. If you were to really do this,
| you'd have to manually test everything anyways before selling
| it. A decade ago what you described would have been called "a
| lazy cashgrab".
| promiseofbeans wrote:
| Given my super limited experience working on the most basic
| bare bones of iOS apps, I would pay for this.
| porcoda wrote:
| Glad I'm not alone. I'm a relatively senior developer who's
| worked 30+ years on a ton of different systems, and every time I
| wade into the Apple ecosystem in the last 10 years or so to build
| a native application for macOS I feel like an idiot since it's
| much harder to find what I need to know to accomplish something.
| I always assumed it was because I wasn't their target
| demographic: I don't do iOS apps, and the things I want to write
| are often not just a matter of throwing together a bunch of
| widgets and a data model and calling it good. I guess their
| terrible documentation isn't a me problem, but an Apple problem.
|
| Add to that the annoying use of videos: I hate finding out that
| something I'm interested in is buried in a WWDC video instead of
| written up. I don't have time or the desire to watch videos as
| reference material: please stop.
| hkpack wrote:
| I have the opposite experience. After a decade of backend work,
| I had to write an app for Windows, macOS and iOS.
|
| The latest SwiftUI is just the best with modern "reactive"
| approaches working really well. Good community and documented
| patterns of how things should be developed, packaged and
| deployed.
|
| The closest alternative is Electron.
|
| The native Windows development is just terrible with tens
| different ways and frameworks which were abandoned by Microsoft
| at one time or another.
| krackers wrote:
| > I'm interested in is buried in a WWDC video
|
| Or even worse, in a wwdc video that apple has tried to scrub
| off the face of the internet (anything older than 2017). I
| still don't understand why they would do this.
| lapcat wrote:
| > 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 Archive", it still contains a
| lot useful information, especially for Mac and Objective-C
| development.
| https://developer.apple.com/library/archive/navigation/
|
| I taught myself Mac development way back in the day using those
| very docs, which are now sadly "retired".
|
| In my view, there are several reasons for the severe decline of
| Apple's docs. First, the yearly OS release schedule, which began
| in 2012 on the Mac, didn't leave enough time to write
| documentation. (And it doesn't leave enough time to fix bugs!)
| Second, the arrival of Swift in 2014 forced Apple to rewrite all
| of the documentation with dual tracks for Swift and Objective-C.
| Third, Tim Cook and Craig Federighi just don't give a crap about
| quality.
|
| > Badly designed, legacy OOP APIs
|
| That sounds like a n00b opinion.
| matwood wrote:
| Yeah. The Objc docs for coding Mac and early iOS apps was quite
| good. I used it extensively.
| jorvi wrote:
| I weep when I read their older HIG for macOS and then see how
| hard they violate so many of the principles and lessons they
| laid down there.
| silvestrov wrote:
| 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
|
| 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.
| dack wrote:
| There's no reason they can't have amazing documentation, but I
| imagine they don't because people are going to use the platform
| anyway. People are basically forced to use it because that's
| where so many of their customers are, so they can just treat
| their users like crap and get away with it. Why spend time on
| documentation when it will probably only cost them money to do
| so?
|
| Such a sad state of affairs.
| TheAceOfHearts wrote:
| Does Apple have developer relations engineers? Surely they must
| have some engineers that participate on social media, and they
| could be asked directly.
|
| It's honestly baffling that we have no mechanism by which to
| increase accountability within technical domains from these large
| corporations.
|
| And if you reach out to Apple, you're more than likely to get
| either radio silence or a canned PR response that doesn't answer
| anything.
|
| It makes me wish that we had powerful technical figures willing
| to hold other tech figures accountable in public. Why isn't there
| anyone capable of setting up an interview with the Apple CTO and
| questioning them directly on the importance of developer tooling
| and relations?
| scyzoryk_xyz wrote:
| They're weird because supposedly their processes and
| documentation predate many others. It's as if they're gradually
| becoming the soviet kremlin. Still good at all that secrecy
| stuff, but the actual processes behind that opaqueness
| increasingly more stubborn and clunky.
|
| Like a deaf grandpa still being able to do great stuff but not
| remembering to keep the shop in order or to take notes so you
| have to ask loudly.
| krackers wrote:
| >Does Apple have developer relations engineers
|
| There's a few that participate in the apple developer forums
| (quinn is the most notable one). There's also DTS tickets which
| you can file
| carterschonwald wrote:
| My fuzzy understanding is that organizationally, the teams / org
| that was originally responsible for writing good documentation at
| Apple became the App Store review teams. And thus never again was
| there time for writing good docs.
| lapcat wrote:
| > My fuzzy understanding is that organizationally, the teams /
| org that was originally responsible for writing good
| documentation at Apple became the App Store review teams.
|
| Not sure where you got that, but I know some people inside
| Apple, and it sounds totally wrong and baseless.
| deanCommie wrote:
| Sorry, this really feels like a user problem. Someone who is used
| to functional or dynamically-typed languages where one has to
| read documentation in a browser instead of just navigating around
| a strongly-typed SDK codebase and understanding how it works from
| within the IDE.
|
| I have done ZERO development in Apple/iOS/macOS. I have written
| ZERO lines of Swift or Objective C. My experience is with Java
| and C#.
|
| But when I opened the first link in the blog that took me to
| https://developer.apple.com/documentation/appkit/nsopenpanel the
| very first thing I saw was
|
| class NSOpenPanel : NSSavePanel
|
| And after scrolling through the page, before I even went back to
| the author's blog I had already clicked on "NSSavePanel", saw
| what was listed there
| https://developer.apple.com/documentation/appkit/nssavepanel, and
| then even further up to
| https://developer.apple.com/documentation/appkit/nspanel, and so
| on.
|
| For me, this was absolutely the most natural way to navigate
| around an unfamiliar SDK/library/codebase. Understand everything
| that's available on the object from it's inheritance chain.
|
| So when I went back to the blog and eventually came to:
|
| > Ah, it inherits from NSSavePanel! That was not at all obvious
| (and I'm sorry OOP devotees, that makes damn all sense in
| principle). Oh, look, loads of new functions and properties. Ah,
| so I'm meant to query the NSOpenPanel object for the directory.
|
| I was extremely confused.
|
| I'm far from an OOP devotee, but I don't understand how you can
| attempt to write code in an OO-language without understanding
| that inheritance is one of the most important concepts for code
| separation. (and is almost always an anti-pattern, but
| regardless).
|
| This is all absolutely information I would expect to discover
| from within my IDE, I wouldn't even go to the browser for it.
|
| I suppose I will have to admit that "Open Panel" inheriting from
| "Save Panel" is weird - it's definitely a code-reuse paradigm and
| not a correct use of "isa" inheritance. Except this is literally
| how it works in every other desktop UI framework I remember using
| - MFC, Visual Basic, Java Swing. I could be wrong, but I think
| it's a pretty common convention in desktop UI development.
| malfist wrote:
| I agree with you. Everything this person is struggling with is
| well documented on the parent class. A basic understanding of
| OOP is all that's needed to use this documentation and this
| dialog.
|
| Are they mad at Java docs? Or C# docs? Or any other OOP doc
| that follows the same pattern of not repeating the parent's
| documention on the subclass unless the subclass adds to it.
| arthurofbabylon wrote:
| Maybe I'm a bit of an outlier, or maybe personally outdated, but
| I find Apple's documentation to be generally good, albeit
| requiring patience.
|
| Apple's documentation offers neither examples nor answers to
| common questions (features of stellar documentation), however it
| works well with a first principles, read-it-twice mentality. The
| key info is there, just not emphasized.
|
| For those who read the documentation twice and feel comfortable
| organizing the architecture without guidance, the documentation
| is highly workable.
|
| I wonder if folks more grounded in web development favor a
| quicker, architecture-agnostic, copy/paste, just-work-out-the-box
| style of documentation. (When I'm working on the web, I do!) But
| Apple's platforms are native, their frameworks build upon native
| infrastructure, and so they require consideration of the
| fundamentals and underlying systems, features that preclude just-
| give-me-the-snippet development.
|
| (That's my take, with my own biases. I don't mean to contradict
| or put down any other perspectives. I am certain that in many
| ways, including many of which I am unaware, I am naive.)
| redandblack wrote:
| Additionally imho, Apple does a fantastic job in "naming"
| things, everywhere in their ecosystem - including their SDK
___________________________________________________________________
(page generated 2024-01-07 23:00 UTC)