17 ms·

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

164 points by imbnwa 3y ago

jitl 3y ago
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 3y ago
  I'm dreaming of the day there would be a chatgpt like thing for all those internal proprietary tools and their "documentation"
  - jitl 3y ago
    What’s the difference you’re imagining from today’s ChatGPT?
    - eurekin 3y ago
      ChatGPT knows nothing of those libraries and their code. I can't paste anything into context, because of security reasons :)
      - jitl 3y ago
        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 https://sourcegraph.com/cody
- asimpson 3y ago
  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 3y ago
  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.
- MarkMarine 3y ago
  100% I put the query in the top of the page into chatGPT with the same requirements (Mac OS, in swift) and I got back detailed explanations, sample code, and basically all the writer was looking for. Not great that OpenAI is serving as better docs than apple’s own, but at least there is an alternative.
- jwells89 3y ago
  ChatGPT has been similarly helpful for working with xcb/xlib and teasing out the arcane bits of X11. I don’t know how anybody had the patience to sift through the scattered writings on those things before… maybe I just don’t know where to look but I find it much more challenging to dredge up info for than anything related to Apple platform development.
  - skydhash 3y ago
    > I don’t know how anybody had the patience to sift through the scattered writings on those things before. Foundational knowledge. Before you delve into x11, you learn how graphics works at the lower level first, and then you build upon this. Before the actual implementation, there was a design. Once you figure it out, you can guess how the implementation is done. You confirm your guess from the docs and code if it’s available.
peterbmarks 3y ago
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 https://developer.apple.com/tutorials/swiftui
lukeh 3y ago
It’s a pity when you consider how detailed Inside Macintosh was.
madsbuch 3y ago
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 3y ago
  I'm pretty sure both of those count as documentation. https://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/ 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.
  - madsbuch 3y ago
    Yep, you are right. I was not precise enough.
- jitl 3y ago
  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.
  - madsbuch 3y ago
    Wow, that was indeed a hot take in my original comment. Net 5 downvotes for a comment that is not at all slurs and represent a genuine opinion about the future of software development. Anyhow, I am concerned about how the new wave of AI tech is going to affect the software development market. A lot of people are focusing on code synthesis. I don't think that is just around the corner. I think think it is going to be in assistive technology, such as learning / helping writing code. I also think a lot of contemporary programmers are attached to documentation and overly focus on it's value, which indeed was important in an age of that being the only way to disseminate the intended workings of a library. I can say that already know https://inkeep.com/ https://inkeep.com/ is working on this type of tech (The I prefer over reading documentation on bun.sh), Pulumi also have https://www.pulumi.com/ai https://www.pulumi.com/ai that I prefer over reading Pulumi's documentation. Anyhow, the future will show how this works out.
ToucanLoucan 3y ago
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 3y ago
Don't forget, one of the things you get for the $99/year developer fee is documentation. https://developer.apple.com/support/compare-memberships/ https://developer.apple.com/support/compare-memberships/
- srajabi 3y ago
  Does this mean you get additional documentation then the example in the blog? Or is that $99 for the bad documentation?
  - chedabob 3y ago
    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 3y ago
  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.
  - lostlogin 3y ago
    > as well as test your apps on devices. If only it was simple. I had a paid account and lots of test devices. I let it lapse. Now I can’t test on my own device with my normal iCloud account as I have too many registered devices for a free account, and I can’t access the interface for deleting those old devices. This edge case has existed since ‘free’ accounts came into existence.
jackblemming 3y ago
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 3y ago
  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 3y ago
    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/ https://docs.flutter.dev/
    - n_plus_1_acc 3y ago
      Flutter is a very leaky abstraction
      - mdhb 3y ago
        Want to provide some examples?
        n_plus_1_acc 3y ago
        For example, there's this package to test Internet connectivity (I know just trying is the best solution). Its readme says > On Android, this does not guarantee connection to Internet. For instance, the app might have wifi access but it might be a VPN or a hotel WiFi with no access. While I unterstand the technical reasons for this limitation, I don't get why it's different on Android. What happens on iOS or web builds? Also check out this FAQ which is full of platform internals which I don't want to care about. If I need to know what permission from the library map to which platform-specific permission, it's not doing a very good job at Abstraktion. And yes, it is a very hard problem. https://pub.dev/packages/permission_handler#faq https://pub.dev/packages/permission_handler#faq
bowsamic 3y ago
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 3y ago
  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.
  - bowsamic 3y ago
    I totally agree. The code supporting the “concise” framework is so complicated it’s almost impossible to add any functionality
simonw 3y ago
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 3y ago
  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/TextFonts/Conceptual/CocoaTextArchitecture/Introduction/Introduction.html#//apple_ref/doc/uid/TP40009459 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.
  - mschuster91 3y ago
    > 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. And writing good documentation involves a fair bit of QA and remediation effort as well - you don't want your consumers to yell at clouds "why is the stuff in the official documentation not working", so the writers should actually go and test stuff themselves to see if the docs are actually still valid. This is what permanently burned my relations with Openstack - half the stuff in the docs was broken when I tried it, either from old age or never being tested out of Redhat.
- shp0ngle 3y ago
  In the old days, they needed to convince people to work on Apple-specific APIs. Mac OS X was miniscule (smaller than today), iOS was either new or didn't even exist. Nowadays, folks have to develop for iOS whether they like it or not, and macOS is on the backburner.
hoc 3y ago
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 3y ago
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 3y ago
  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 3y ago
  Given my super limited experience working on the most basic bare bones of iOS apps, I would pay for this.
- nmfisher 3y ago
  I've actually been waiting for something similar - basically some kind of LLM-powered auto-reviewer that checks whether the documentation and the code are in sync on commit. I've seen so much outdated documentation recently that I'm starting to ignore it and go straight to code (+1 for open source I guess).
porcoda 3y ago
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 3y ago
  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.
  - manmal 3y ago
    For the use case of presenting JSON in a pretty way, SwiftUI is great - let’s call that the happy path. But Flutter is also great at that, and you’d only need one implementation that way. The problems begin when you are doing less trivial or obvious things on iOS/Mac, like interacting with Bluetooth, or displaying large amounts of data in a list, or forms that scroll like your designer wants them to, or background processing, or…
  - araes 3y ago
    Currently wading through WinRT, and all things look good compared to the WinRT experience. Layers of false layers of false layers of false laysers ... until you get to, pointer. HorribleRunOnNameLandOfNoEnd::ThatGoesForeverOffThePageOnEverySingleFunctionCall::WithMassiveChainsThatCompletelyOverwhelmTheirOwnIDE::AndMakeYouTrailYourVisionAcrossMassiveGulfsOfTimeAndSpace::ToFind( int* ptr ) You grab some command line example off the web that seems kind of simple and get: ExternalDependencies[7777]: 1: _msvc_bit_utils.hpp 1000: DirectXMath.h (?? it's not a graphics app) 2000: joystickapi.h (?? same. totally confused) 3000: processtopologyapi.h (?? we're doing topology calcs?) 4000: windows.devices.smartcards.0.h (?? not a smartcard app) 5000: xpolymorphic_allocator.h And in using the IDE for a week or so, I've already found so many bugs I don't know what to do. Functions are perpetually listed broken because of an array upfield slightly wrong. It seems compelled to format my code the absolutely worst way available at any given time. It would be better to simply turn off formatting. And ... their example broke. Inside of a bag maze I had no interest in navigating.
lapcat 3y ago
> 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/ 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 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.
dack 3y ago
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.
- euroderf 3y ago
  Your treatment-as-crap is Apple's MAKE-GOB$-OF-CA$H. Need I elucidate ?
TheAceOfHearts 3y ago
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 3y ago
  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 3y ago
  >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
- lawgimenez 3y ago
  Every WWDC is a good time to get in touch with them where they host Slack chats.
  - saagarjha 3y ago
    Great! I only have questions once a year and this is prefect for me!
- saagarjha 3y ago
  Apple doesn’t really have a social media policy. Their default go-to is “don’t”.
carterschonwald 3y ago
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 3y ago
  > 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 3y ago
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 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 https://developer.apple.com/documentation/appkit/nssavepanel, and then even further up to https://developer.apple.com/documentation/appkit/nspanel 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 3y ago
  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 3y ago
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 3y ago
  Additionally imho, Apple does a fantastic job in "naming" things, everywhere in their ecosystem - including their SDK
  - jwells89 3y ago
    The overly descriptive names get made fun of online, but they’re frequently self-explanatory enough that they can be pulled from autocomplete, skipping the documentation entirely.
- fingerlocks 3y ago
  Yeah I’m with you. I don’t understand what everyone is complaining about. There’s a few things that are undocumented here and there (IOSurfaceRef) but you can sniff out how it works with a little trial and error. I often code offline with only the Apple docs as reference, not a problem.
  - eviks 3y ago
    How much trial and error to sniff out 80%? "Core Audio 124 / 618 (20.1%"
deleted 3y ago
[deleted]
mung 3y ago
It's why I never really bothered with Mac OS or iOS development. I don't have time to waste searching for answers. What an absolute PITA. I like learning from 3rd party sources, but there HAS to be an official, maintained 1st party source or there is no point.
lawgimenez 3y ago
Recently have the same experience, I was writing a small SwiftUI app for macOS and wanted to detect the hardware keys and handle it, especially the Delete key. It was hard to find it in Apple’s doc. But I figured it out with some random blog and a lot of print() on my end.
smallstepforman 3y ago
Meanwhile, here are the Haiku docs for BFilePanel (thanks BeInc for great docs). Who said C++ was hard to use? https://www.haiku-os.org/legacy-docs/bebook/BFilePanel_Overview.html https://www.haiku-os.org/legacy-docs/bebook/BFilePanel_Overv...
cc101 3y ago
I hesitate to defend Apple developer documentation. I have struggled with it for 30 some years, but if you don't understand OOP on the mac (inheritance etc.), you probably shouldn't attempt to program the mac. This reminds me of a UNIX programmer I worked with who called up our Apple sales rep and berated her and Apple because programming macOS wasn't like programing UNIX. When I called her to apologize, she was nearly in tears. You are way outside this field. Programming the macOS can be very different and difficult. Either learn its concepts or work on something else.
- deleted 3y ago
  [deleted]
- eviks 3y ago
  Docs are the place people go to to learn the concepts. Examples is one way how docs teach those concepts.
DueDilligence 3y ago
[dead]
ptek 3y ago
Off topic: Documentation seems good on Next Step 3.3 and OpenStep 4.2 Developer CD.
scrubs 3y ago
Atomization is one of the unfortunate side effects of the web. What's worse than Apple docs? NVIDIA/Mellanox docs. Use-cases are tucked away in 75 million different URLs, web pages, power-points, .txt docs, stack overflow posts and what not. I long for time and place where I can download a standalone user-guide, a technical guide, and an API reference as PDFs and rendered as searchable docs.
idlephysicist 3y ago
Every now and then I dust off Xcode to try and build myself some (pretty simple) native macOS app – just for funsies. For reference I am a backend dev at a SaaS company dealing primarily in Python & Go, doing HTTP/gRPC services and talking to databases. Last night I attempted to make a program that would display an image and allow the user to click the image and then display the hex value of the colour under the cursor. I wanted my application to use a crosshair cursor and after an hour of looking at the docs for NSCursor[1] and stackoverflow I just gave up. I don't know how someone gets started in this ecosystem but I am sure once you know it this stuff is easy. [1] https://developer.apple.com/documentation/appkit/nscursor https://developer.apple.com/documentation/appkit/nscursor
- jwells89 3y ago
  It’s in the page you linked under set(). Combined with the properties at the top of the documentation page, to make the cursor a crosshair you’d call NSCursor.crosshair.set(), after which it’ll remain that cursor until something else changes it (so for instance, you’ll need to call it whenever the cursor enters the relevant view since e.g. crossing window borders will change the cursor).
mleonhard 3y ago
I'm dealing with this daily as I build Applin. Example from Friday: I spend about an hour figuring out why my iOS app was not showing an error response when the server refused an upload. The iOS standard library URLRequest class was not sending the "Expect:100-Continue" HTTP header. I found nothing about this in the docs. I found the answer on Stack Overflow: add the header to the request and the class will automatically use it and wait for the "100 Continue" response before sending the body. Last week, I spent multiple hours getting UIPickerView to work. The docs omit critical info like how to update the widget. Also, the API design is confusing: one must implement UIPickerViewDataSource but that isn't actually used as the source of the data, only the count of components. To make the picker work, one has to implement UIPickerViewDelegate which provides the actual data. It's a very confusing widget. Earlier in this project, I wasted multiple weeks struggling, unsuccessfully, to get UITableView and UIStackView to work for my use-case. This took so long because the docs are missing lots of important info. Shameless plug: Backend engineers can use Applin to build iOS apps, without writing any frontend code and without struggling to understand Apple's poorly-documented buggy APIs. https://www.applin.dev https://www.applin.dev
alexeiz 3y ago
That NSOpenPanel class reminds me of MFC days. For those young enough to remember, it's Microsoft Foundation Classes, the UI framework for Windows. Everything had to be a class in MFC: new window - a class, file open dialog - a class. In order to understand what you code does, you have to analyze the whole hierarchy of classes, and figure out where that particular virtual method that you need is implemented. Deep inheritance hierarchies of MFC coined the term "fragile base class" problem where changes to a base class can inadvertently affect the behavior of derived classes, potentially causing them to malfunction or behave in unexpected ways.

164 points by imbnwa 3y ago

jitl 3y ago

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 3y ago
I'm dreaming of the day there would be a chatgpt like thing for all those internal proprietary tools and their "documentation"
- jitl 3y ago
  What’s the difference you’re imagining from today’s ChatGPT?
  - eurekin 3y ago
    ChatGPT knows nothing of those libraries and their code. I can't paste anything into context, because of security reasons :)
    - jitl 3y ago
      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 https://sourcegraph.com/cody
asimpson 3y ago
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 3y ago
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.
MarkMarine 3y ago
100% I put the query in the top of the page into chatGPT with the same requirements (Mac OS, in swift) and I got back detailed explanations, sample code, and basically all the writer was looking for. Not great that OpenAI is serving as better docs than apple’s own, but at least there is an alternative.
jwells89 3y ago
ChatGPT has been similarly helpful for working with xcb/xlib and teasing out the arcane bits of X11. I don’t know how anybody had the patience to sift through the scattered writings on those things before… maybe I just don’t know where to look but I find it much more challenging to dredge up info for than anything related to Apple platform development.
- skydhash 3y ago
  > I don’t know how anybody had the patience to sift through the scattered writings on those things before. Foundational knowledge. Before you delve into x11, you learn how graphics works at the lower level first, and then you build upon this. Before the actual implementation, there was a design. Once you figure it out, you can guess how the implementation is done. You confirm your guess from the docs and code if it’s available.

peterbmarks 3y ago

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 https://developer.apple.com/tutorials/swiftui

lukeh 3y ago

It’s a pity when you consider how detailed Inside Macintosh was.

madsbuch 3y ago

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 3y ago
I'm pretty sure both of those count as documentation. https://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/ 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.
- madsbuch 3y ago
  Yep, you are right. I was not precise enough.
jitl 3y ago
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.
- madsbuch 3y ago
  Wow, that was indeed a hot take in my original comment. Net 5 downvotes for a comment that is not at all slurs and represent a genuine opinion about the future of software development. Anyhow, I am concerned about how the new wave of AI tech is going to affect the software development market. A lot of people are focusing on code synthesis. I don't think that is just around the corner. I think think it is going to be in assistive technology, such as learning / helping writing code. I also think a lot of contemporary programmers are attached to documentation and overly focus on it's value, which indeed was important in an age of that being the only way to disseminate the intended workings of a library. I can say that already know https://inkeep.com/ https://inkeep.com/ is working on this type of tech (The I prefer over reading documentation on bun.sh), Pulumi also have https://www.pulumi.com/ai https://www.pulumi.com/ai that I prefer over reading Pulumi's documentation. Anyhow, the future will show how this works out.

ToucanLoucan 3y ago

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 3y ago

Don't forget, one of the things you get for the $99/year developer fee is documentation. https://developer.apple.com/support/compare-memberships/ https://developer.apple.com/support/compare-memberships/

srajabi 3y ago
Does this mean you get additional documentation then the example in the blog? Or is that $99 for the bad documentation?
- chedabob 3y ago
  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 3y ago
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.
- lostlogin 3y ago
  > as well as test your apps on devices. If only it was simple. I had a paid account and lots of test devices. I let it lapse. Now I can’t test on my own device with my normal iCloud account as I have too many registered devices for a free account, and I can’t access the interface for deleting those old devices. This edge case has existed since ‘free’ accounts came into existence.

jackblemming 3y ago

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 3y ago
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 3y ago
  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/ https://docs.flutter.dev/
  - n_plus_1_acc 3y ago
    Flutter is a very leaky abstraction
    - mdhb 3y ago
      Want to provide some examples?
      - n_plus_1_acc 3y ago
        For example, there's this package to test Internet connectivity (I know just trying is the best solution). Its readme says > On Android, this does not guarantee connection to Internet. For instance, the app might have wifi access but it might be a VPN or a hotel WiFi with no access. While I unterstand the technical reasons for this limitation, I don't get why it's different on Android. What happens on iOS or web builds? Also check out this FAQ which is full of platform internals which I don't want to care about. If I need to know what permission from the library map to which platform-specific permission, it's not doing a very good job at Abstraktion. And yes, it is a very hard problem. https://pub.dev/packages/permission_handler#faq https://pub.dev/packages/permission_handler#faq

bowsamic 3y ago

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 3y ago
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.
- bowsamic 3y ago
  I totally agree. The code supporting the “concise” framework is so complicated it’s almost impossible to add any functionality

simonw 3y ago

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 3y ago
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/TextFonts/Conceptual/CocoaTextArchitecture/Introduction/Introduction.html#//apple_ref/doc/uid/TP40009459 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.
- mschuster91 3y ago
  > 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. And writing good documentation involves a fair bit of QA and remediation effort as well - you don't want your consumers to yell at clouds "why is the stuff in the official documentation not working", so the writers should actually go and test stuff themselves to see if the docs are actually still valid. This is what permanently burned my relations with Openstack - half the stuff in the docs was broken when I tried it, either from old age or never being tested out of Redhat.
shp0ngle 3y ago
In the old days, they needed to convince people to work on Apple-specific APIs. Mac OS X was miniscule (smaller than today), iOS was either new or didn't even exist. Nowadays, folks have to develop for iOS whether they like it or not, and macOS is on the backburner.

hoc 3y ago

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 3y ago

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 3y ago
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 3y ago
Given my super limited experience working on the most basic bare bones of iOS apps, I would pay for this.
nmfisher 3y ago
I've actually been waiting for something similar - basically some kind of LLM-powered auto-reviewer that checks whether the documentation and the code are in sync on commit. I've seen so much outdated documentation recently that I'm starting to ignore it and go straight to code (+1 for open source I guess).

porcoda 3y ago

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 3y ago
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.
- manmal 3y ago
  For the use case of presenting JSON in a pretty way, SwiftUI is great - let’s call that the happy path. But Flutter is also great at that, and you’d only need one implementation that way. The problems begin when you are doing less trivial or obvious things on iOS/Mac, like interacting with Bluetooth, or displaying large amounts of data in a list, or forms that scroll like your designer wants them to, or background processing, or…
- araes 3y ago
  Currently wading through WinRT, and all things look good compared to the WinRT experience. Layers of false layers of false layers of false laysers ... until you get to, pointer. HorribleRunOnNameLandOfNoEnd::ThatGoesForeverOffThePageOnEverySingleFunctionCall::WithMassiveChainsThatCompletelyOverwhelmTheirOwnIDE::AndMakeYouTrailYourVisionAcrossMassiveGulfsOfTimeAndSpace::ToFind( int* ptr ) You grab some command line example off the web that seems kind of simple and get: ExternalDependencies[7777]: 1: _msvc_bit_utils.hpp 1000: DirectXMath.h (?? it's not a graphics app) 2000: joystickapi.h (?? same. totally confused) 3000: processtopologyapi.h (?? we're doing topology calcs?) 4000: windows.devices.smartcards.0.h (?? not a smartcard app) 5000: xpolymorphic_allocator.h And in using the IDE for a week or so, I've already found so many bugs I don't know what to do. Functions are perpetually listed broken because of an array upfield slightly wrong. It seems compelled to format my code the absolutely worst way available at any given time. It would be better to simply turn off formatting. And ... their example broke. Inside of a bag maze I had no interest in navigating.

lapcat 3y ago

> 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/ 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 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.

dack 3y ago

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.

euroderf 3y ago
Your treatment-as-crap is Apple's MAKE-GOB$-OF-CA$H. Need I elucidate ?

TheAceOfHearts 3y ago

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 3y ago
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 3y ago
>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
lawgimenez 3y ago
Every WWDC is a good time to get in touch with them where they host Slack chats.
- saagarjha 3y ago
  Great! I only have questions once a year and this is prefect for me!
saagarjha 3y ago
Apple doesn’t really have a social media policy. Their default go-to is “don’t”.

carterschonwald 3y ago

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 3y ago
> 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 3y ago

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 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 https://developer.apple.com/documentation/appkit/nssavepanel, and then even further up to https://developer.apple.com/documentation/appkit/nspanel 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 3y ago
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 3y ago

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 3y ago
Additionally imho, Apple does a fantastic job in "naming" things, everywhere in their ecosystem - including their SDK
- jwells89 3y ago
  The overly descriptive names get made fun of online, but they’re frequently self-explanatory enough that they can be pulled from autocomplete, skipping the documentation entirely.
fingerlocks 3y ago
Yeah I’m with you. I don’t understand what everyone is complaining about. There’s a few things that are undocumented here and there (IOSurfaceRef) but you can sniff out how it works with a little trial and error. I often code offline with only the Apple docs as reference, not a problem.
- eviks 3y ago
  How much trial and error to sniff out 80%? "Core Audio 124 / 618 (20.1%"

deleted 3y ago

[deleted]

mung 3y ago

It's why I never really bothered with Mac OS or iOS development. I don't have time to waste searching for answers. What an absolute PITA. I like learning from 3rd party sources, but there HAS to be an official, maintained 1st party source or there is no point.

lawgimenez 3y ago

Recently have the same experience, I was writing a small SwiftUI app for macOS and wanted to detect the hardware keys and handle it, especially the Delete key. It was hard to find it in Apple’s doc. But I figured it out with some random blog and a lot of print() on my end.

smallstepforman 3y ago

Meanwhile, here are the Haiku docs for BFilePanel (thanks BeInc for great docs). Who said C++ was hard to use? https://www.haiku-os.org/legacy-docs/bebook/BFilePanel_Overview.html https://www.haiku-os.org/legacy-docs/bebook/BFilePanel_Overv...

cc101 3y ago

I hesitate to defend Apple developer documentation. I have struggled with it for 30 some years, but if you don't understand OOP on the mac (inheritance etc.), you probably shouldn't attempt to program the mac. This reminds me of a UNIX programmer I worked with who called up our Apple sales rep and berated her and Apple because programming macOS wasn't like programing UNIX. When I called her to apologize, she was nearly in tears. You are way outside this field. Programming the macOS can be very different and difficult. Either learn its concepts or work on something else.

deleted 3y ago
[deleted]
eviks 3y ago
Docs are the place people go to to learn the concepts. Examples is one way how docs teach those concepts.

DueDilligence 3y ago

[dead]

ptek 3y ago

Off topic: Documentation seems good on Next Step 3.3 and OpenStep 4.2 Developer CD.

scrubs 3y ago

Atomization is one of the unfortunate side effects of the web. What's worse than Apple docs? NVIDIA/Mellanox docs. Use-cases are tucked away in 75 million different URLs, web pages, power-points, .txt docs, stack overflow posts and what not. I long for time and place where I can download a standalone user-guide, a technical guide, and an API reference as PDFs and rendered as searchable docs.

idlephysicist 3y ago

Every now and then I dust off Xcode to try and build myself some (pretty simple) native macOS app – just for funsies. For reference I am a backend dev at a SaaS company dealing primarily in Python & Go, doing HTTP/gRPC services and talking to databases. Last night I attempted to make a program that would display an image and allow the user to click the image and then display the hex value of the colour under the cursor. I wanted my application to use a crosshair cursor and after an hour of looking at the docs for NSCursor[1] and stackoverflow I just gave up. I don't know how someone gets started in this ecosystem but I am sure once you know it this stuff is easy. [1] https://developer.apple.com/documentation/appkit/nscursor https://developer.apple.com/documentation/appkit/nscursor

jwells89 3y ago
It’s in the page you linked under set(). Combined with the properties at the top of the documentation page, to make the cursor a crosshair you’d call NSCursor.crosshair.set(), after which it’ll remain that cursor until something else changes it (so for instance, you’ll need to call it whenever the cursor enters the relevant view since e.g. crossing window borders will change the cursor).

mleonhard 3y ago

I'm dealing with this daily as I build Applin. Example from Friday: I spend about an hour figuring out why my iOS app was not showing an error response when the server refused an upload. The iOS standard library URLRequest class was not sending the "Expect:100-Continue" HTTP header. I found nothing about this in the docs. I found the answer on Stack Overflow: add the header to the request and the class will automatically use it and wait for the "100 Continue" response before sending the body. Last week, I spent multiple hours getting UIPickerView to work. The docs omit critical info like how to update the widget. Also, the API design is confusing: one must implement UIPickerViewDataSource but that isn't actually used as the source of the data, only the count of components. To make the picker work, one has to implement UIPickerViewDelegate which provides the actual data. It's a very confusing widget. Earlier in this project, I wasted multiple weeks struggling, unsuccessfully, to get UITableView and UIStackView to work for my use-case. This took so long because the docs are missing lots of important info. Shameless plug: Backend engineers can use Applin to build iOS apps, without writing any frontend code and without struggling to understand Apple's poorly-documented buggy APIs. https://www.applin.dev https://www.applin.dev

alexeiz 3y ago

That NSOpenPanel class reminds me of MFC days. For those young enough to remember, it's Microsoft Foundation Classes, the UI framework for Windows. Everything had to be a class in MFC: new window - a class, file open dialog - a class. In order to understand what you code does, you have to analyze the whole hierarchy of classes, and figure out where that particular virtual method that you need is implemented. Deep inheritance hierarchies of MFC coined the term "fragile base class" problem where changes to a base class can inadvertently affect the behavior of derived classes, potentially causing them to malfunction or behave in unexpected ways.