5 ms·
The unbearable frustration of figuring out APIs
- alexjray 9mo agoShow me the incentive and I can likely guess how hard your API is to use.
- Svoka 9mo agoThis is strangest read I had in a while. It is like saying that operating a submarine is very counter intuitive, I know how to operate an airliner, both are vehicles.
- stevedonovan 9mo agoIt was my first taste of Swift, and has destroyed any lingering curiosity I had about it.
- bfbf 9mo agoAs a Swift dev, I have to say this was a frustrating read. Apple’s documentation is often very poor, and I will note that Swift Packages (especially CLIs) doesn’t always feel great. As another commenter noted, anything other than Xcode feels like fighting an uphill battle. But many of your frustrations could be solved by checking not API docs, but just the Swift language guide. You seem perturbed, for example, that the Package initializer expects ordered arguments. It is a basic part of Swift’s design that arguments are always ordered and exclusively are either named or unnamed (never optionally both). The ghost’s use of semaphores with async/await is a massive red flag in terms of mixing two asynchronous frameworks (Concurrency and GCD). I’d not be surprised if it worked, but that’s really against the grain in terms of how either framework were designed. This is the shortfall of relying on bottled ghosts to learn new tools. I know from experience that the documentation on Concurrency (async/await) is pretty good, and lays out a clear rationale for how it’s intended to be used, but that is a huge piece of documentation and it’s a big hill to climb when all you’re building is a small tool. This is the risk we run when asking AI for help when it itself is ignorant of the actual intended use of the apis and is only trained on the output of developers. Here it’s easy to see that it was faced with a problem of synchronous access to an async function and reached for a common solution (semaphore), despite the fact that semaphores are part of a 10 year old framework, and the async/await keywords are only 2-3 years old! Anyway, the article reminded me of the challenges of learning a new (programming) language. There’s more to it than just following tutorials and blindly directing AI. I know the feeling, having to currently learn c# at the moment. I can write simple functions and follow the syntax, but I can’t intuitively understand what’s happening like I can with Swift. Is that because Swift is better than C#? Not really- it’s just that I’m fluent in one but not the other. Ironically I guess you probably get this already from learning Mandarin, but you’ve not written an article about how frustrating it is that it inexplicably insists on using tones to express meaning, when English is fine without it(!). I’m sorry you had a bad experience with Swift. I do genuinely think it’s a great language to write, and the open source Swift Evolution team are great. They are continually pushing for more openness and more cross platform compatibility, and I do like the way that the core of the language is strongly opinionated in a way that makes it clear what’s happening if you do understand the syntax. What’s hard is then the application of Apple’s APIs which are wildly inconsistent and often incomplete. Some are maintained while others are still wrappers for 15 year old objective C that have no concept of modern Swift paradigms. That said, I’d still encourage you to persevere with Swift. Once you get past those rough edges of stdio and UI and get into the heart of a Package, I would expect most of these complaints to disappear!
- TeMPOraL 9mo agoMore like, operating a submarine that's being designed and built-up around you as you travel in it, with half the components being obscure military secrets that - for reasons unknown - don't come with operator manuals anymore, and the other half being done by children copying designs they saw in TV shows with duct-tape and plasticine. That's how modern software industry feels like.
- blumenkraft 9mo agoIn all honesty this is how a typical developer experience has been for a long time in a number of systems. Expecting someone to pre-chew your programming food is silly.
- Bratmon 9mo agoThe difference is that most of those systems have documentation that explains how to use their weird APIs.
- dvh 9mo agoFor me the worst APIs by far are on Android. They are even worse than win32.
- behnamoh 9mo agoNope, Google AI APIs are second to none. That shit will make you question whether their services are worth it. Edit: Come to think of it, both are made by Google :')
- taeric 9mo agoAgreed. Amusingly, a lot of what makes them worse than some older alternatives is that they "fix" things constantly by reworking how to use them. Older paths may be bad, but effort has been made into getting them to work.
- m-schuetz 9mo agoCan anything be worse than Vulkan?
- manithree 9mo agoEver used the self-hosted BitBucket (formerly Stash) API?
- a1o 9mo ago> You probably already know this, but apparently the first line in the file, that comment, is actually significant. I did not knew this.
- lacoolj 9mo agoI'm really sorry, but when someone posts an entire article that they don't first proof-read at least once, it makes me question the rest of what I'm reading and can't continue. > ... I found mysekf launching TextEdit just to do that I hope everyone else enjoys it!
- saulpw 9mo agoon the one hand, why didn't they just pump it through the "Ghost" and have it fix all the problems for them? on the other hand, I appreciated knowing that it was actually written by a frustrated human, and not sanitized by the Ghost.
- TeMPOraL 9mo agoThat's the thing: if you ask the Ghost to write as if a frustrated human, it'll happily do so. LLMs are good at style transfer in fully general sense, they can introduce typos and bad grammar just as easily as it can correct them.
- saulpw 9mo agoThat's fine, and I know that, but I have never heard of anyone doing that to publish something 'more human' on their blog. Not to say that it's never happened, but when I see some pretty basic typos in a blog post that also sounds like actual human frustration, Occam's Razor says it's fair to assume that a human made those typos.
- TeMPOraL 9mo agoI've seen non-tech people doing that both by hand and automatically, specifically to make the e-mails and documents look human-authored. I'm convinced this is a very common behavior.
- otikik 9mo agoI like it. It tells me this wasn't written by AI
- marcellus23 9mo agoAll of this is written with a sense of anger and sarcastic invective that doesn't seem appropriate. This is part of learning any new language or API. Going in with an attitude of "I should already know how all this works, why am I forced to do research or look at docs?" seems unfair and will spoil the experience of learning anything. > Why was that so hard? Why are the models here separate from the ones in the right click menu? Too many questions. The very screenshot above this paragraph actually answers this, in what admittedly might be an uncharacteristically clear UI: "Siri and Safari will always run translations online."
- n8cpdx 9mo agoThis is a story about the risks of AI-induced brainrot. You get so used to having the computer just do your work, that the second you need to engage your noggin you’re lost at sea. Or at least just frustrated. Reading and understanding the docs and reference material has always been part of the work. Aside from the commentary it read like an advertisement for how great the swift/macos translation APIs are. PEBCAK
- IncreasePosts 9mo agoThe problem is there are a wide class of problems that you want solved but putting on the work will prevent you from actually doing the task because the cost isn't worth the reward. Because it's for a low impact tool. Or you can't imagine yourself dealing with this API again within a year or two by which time it will probably be completely different with v2 of the API. So, you reach for AI and it works really well. So you start reaching for that more and more...
- adventured 9mo agoHaving no minimum wage for LLMs is fantastic. It opens up all manner of work that had previously been priced out.
- mangamadaiyan 9mo ago
- Johnny_Bonk 9mo agoOne thing you could consider doing, is using Claude in chrome extension and having it help you read through the api docs with you and gather sort of cheatsheet, it's helped me immensely, it can click through and parse pages etc.
- akhil08agrawal 9mo agoThe "finally got it working then realized Spotlight already does this" moment is brutal. API design isn't just about functionality. it is about discoverability and if your right-click menu uses different models than your API and your error messages don't explain why, you are just creating friction for no reason. Sometimes the "proper" solution isn't worth the super complicated maze.
- Shuddown 9mo agoI must be missing something here. Why would anyone want to use Apple's god awful translation models? Is it perhaps better at translating individual words? Anytime I've used it for article translation it has been unequivocally terrible.
- frizlab 9mo agoDid you use it recently? I used it to translate a Chinese website to English and was surprised to see everything made sense. Even the texts on the images were translated (in Safari).
- nabbed 9mo agoWay, way back in 2003 or thereabouts, I had to add an "open this report in Excel" function to an existing product. But first I had to figure out how to convert the report to Excel format (with freeze panes, etc.). I found Apache POI and was very happy with its API documentation, especially this "Busy Developers' Guide to Features": https://poi.apache.org/components/spreadsheet/quick-guide.html https://poi.apache.org/components/spreadsheet/quick-guide.ht... This page was much simpler 22 years ago (I don't remember this HSSF stuff, whatever that is), but it still looks familiar. Basically everything I needed to do had examples in there. I remember thinking that the authors cared about the users of the library (although the Javadoc seems a little bare.. but I am not sure I needed the Javadoc much). If I ever create an OSS library, I would certainly also create a "Busy Developers' Guide".
- another_twist 9mo agoEvery library I have ever considered using and almost all of the ones that I onboarded have a "Quickstart" section. eg Guava, Guice,
- Salgat 9mo agoMy biggest frustration with docs is when they don't provide examples. Seems like whenever examples are included, everything becomes much easier to understand because you have an explicit usage to reference. I've always loved Microsoft's API Browser for this reason: https://learn.microsoft.com/en-us/dotnet/api/system.net.networkinformation.networkinterface.getallnetworkinterfaces?view=net-10.0 https://learn.microsoft.com/en-us/dotnet/api/system.net.netw...
- ks2048 9mo agoNot mentioned in the blog post, but he links to an Apple API documentation page, which itself links to a full sample app using Translation API, https://developer.apple.com/documentation/translation/translating-text-within-your-app https://developer.apple.com/documentation/translation/transl...
- joshstrange 9mo agoTo be fair, Apple is known for having bad docs (for at least the past 5-10 years) that often don’t have examples or sample code, I think that’s more of an outlier. I don’t regularly develop in swift, but when I have, I’ve been confused by the docs because they are so clearly auto generated (not LLM, just from the code) and sparse. Listing out constants is next to useless when they are confusingly named and have no description of what they mean or how the affect things.
- classicsc 9mo agoIf you want the ghosts to hallucinate less on things like this you should hook them up with the sosumi MCP. It's been very helpful to me since it seems like Apple's newer APIs are not in the training set of today's models. When working on my own projects I've found a good rule of thumb to be that if you are being told to use something low level and unintuitive like a semaphore in Swift when doing something that ought to be easy, you are probably either reading a stackoverflow answer from an objective-c developer or in the middle of a LLM session that's gone sideways. Low level libraries might need those things, they are approximately never right for application code. Just throw it out and start over (as you did), saves on sanity.
- mwkaufma 9mo ago"The Unbearable Frustration of Figuring Out APIS... By Just Asking A Chatbot Instead Of Reading The Manual"
- flowerbreeze 9mo agoMy favourite approach to documentation is the "4 kinds of documentation" - whether it's about an API, a library or anything else. I think it's a very clean way of explaining "good/poor" documentation. In a nutshell, which type of documentation we need depends on the goal we have. Any API missing one of the kinds of documentation will feel like it is missing something. Once I read about it, I've been noticing how the documentation I like tends to have all these aspects covered. 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...
- footy 9mo agoI don't understand why people who think like this get (or want to get) jobs as software developers It's clearly not enjoyable for them so why doesn't the author pivot to something else and stop doing things they hate? It's weird
- frizlab 9mo agoMe neither, but it does explain why AI is so popular…
- another_twist 9mo agoBecause the time investment isnt worth it most of the time. Unless its a widely used framework / library its worth no ones time to try and understand API docs, each and every component and then deal with some genius patterns thrown here and here. Its a skill that has low market value so sharpening it isnt worth it.
- footy 9mo agoright but not all things are done for "market value" reasons, and that's kind of my point. If you don't find this stuff interesting, what's the point of building your career in the space?
- talentedcoin 9mo agoThey seem to be unemployed (maybe for a reason)
- frizlab 9mo agoTangentially related, I did a project (forked, but fully rewrote) to be able to avoid the Package.swift file for single file projects like these. [1] The general idea is a bit like uv if I have understood uv correctly. Basically you do your imports normally and add a comment next to them that tells where the imports should be found. Then instead of running your project through swift directly you run it through swift-sh (or `swift sh`, swift will find the `swift-sh` binary automatically, just like git does for plugins). swift-sh will download and compile the dependencies, then add the proper options to swift so it will know where to find them. It is even possible to add a regular shebang to swift-sh at the beginning of the file, chmod +x it, and just run it like a regular script! Or use swift-sh to compile it. (And installing swift-sh itself is as easy as `brew install xcode-actions/tap/swift-sh`.) [1] https://github.com/xcode-actions/swift-sh https://github.com/xcode-actions/swift-sh
- mayoff 9mo agoThank you for this. I’ve been using it for years.
- MORPHOICES 9mo ago[dead]
- talentedcoin 9mo agoThis seems like the most ineffective way possible to figure out an API
- VerifiedReports 9mo ago"how the API to use it looks like"? Maybe English is another of the API frustrations that led to this screed.