All 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."
This 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
Gotta say as a Swift dev I agree—followed the link the to Translate docs and was pleasantly surprised to see a discussion section clearly explaining the usage, which is not always the case for Apple APIs! But this wasn’t really just an article about the API. It was about the complexity of trying to build on the stack of Swift/SPM/ParseableCommand/Foundation/Concurrency/Translation without having a good grasp of any of them. I was frustrated reading it, but I think it does point to the underlying knowledge that’s needed to be proficient at something like this. None of it is a particular indictment of Swift as an ecosystem (though there are lots of valid criticisms)-it’s just the nature of development and something that’s massively eroded by relying too much on these ghosts
I remember reading and hearing similar rants from programmers 15 years ago, long before LLMs. The author kept going and figured it out, and probably got some pride and enjoyment from finishing the project in spite of the frustrating moments. That’s what learning to code has always been like.
The 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...
Disagree here. APIs are meant for using and not learning. But the context matters here. For some paid system, there better be an API thats easy to use or I am throwing AI at the problem or hoping someone else will do it. If its something worth learning - say Guava data structures or RocksDb core - yup I'll invest the time to learn. That learning transfers over. But trying to learn some shitty AWS api and its nuances, no thanks. Some payment system that a handful of people use - no thanks again.
Coming from other languages, figuring out how to get an NWConnection to work was not trivial and just reading the interface docs did not help. I empathise with the frustration of reading apple docs. Sure, the tone isn’t professional, but I don’t believe that is out of place.
Most of the author's frustration was due to lack of good feedback from Swift.
Like, how can it run a command that has an `async` main despite the fact that you didn't extend the async version of command?? That should've been an error (e.g. "bro, you cannot have an async main in this class, you need the Async version of this class which is called AsyncWhatever").
Not awaiting on an async function should be at least a warning. Another frustrating lack of feedback: it just lets you run it and nothing happens.
The version thing: it should show all possible variants in the enum, even the ones you should not be able to use, and then when you try using it, show an error saying "you need to change the version of this file to at least blah to use this". Why can't the Swift LSP do that? Apple has a trillion dollars, they can afford polishing their stuff.
The author is used to Rust, which would've made it very clear what was wrong in all cases.
Swift, being as modern as Rust, should be doing better than that. Languages that fail to give you proper error messages and warnings are just not worth it: just one of these "wtf is going on?" moments can cost you hours. Just use a better language if you can.
Way, 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.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".
My 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.
Tangentially 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`.)
My 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.
The "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.
If 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.
Agreed. 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.
One 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.
In 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.
This 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.
More 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.
As 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!
I'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 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.
Did 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).
Because 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.
All 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."
This 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
Gotta say as a Swift dev I agree—followed the link the to Translate docs and was pleasantly surprised to see a discussion section clearly explaining the usage, which is not always the case for Apple APIs! But this wasn’t really just an article about the API. It was about the complexity of trying to build on the stack of Swift/SPM/ParseableCommand/Foundation/Concurrency/Translation without having a good grasp of any of them. I was frustrated reading it, but I think it does point to the underlying knowledge that’s needed to be proficient at something like this. None of it is a particular indictment of Swift as an ecosystem (though there are lots of valid criticisms)-it’s just the nature of development and something that’s massively eroded by relying too much on these ghosts
I remember reading and hearing similar rants from programmers 15 years ago, long before LLMs. The author kept going and figured it out, and probably got some pride and enjoyment from finishing the project in spite of the frustrating moments. That’s what learning to code has always been like.
The 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...
Having no minimum wage for LLMs is fantastic. It opens up all manner of work that had previously been priced out.
Disagree here. APIs are meant for using and not learning. But the context matters here. For some paid system, there better be an API thats easy to use or I am throwing AI at the problem or hoping someone else will do it. If its something worth learning - say Guava data structures or RocksDb core - yup I'll invest the time to learn. That learning transfers over. But trying to learn some shitty AWS api and its nuances, no thanks. Some payment system that a handful of people use - no thanks again.
Language is meant for using, not learning. Why is Arabic/French/Chinese/etc so difficult?
Coming from other languages, figuring out how to get an NWConnection to work was not trivial and just reading the interface docs did not help. I empathise with the frustration of reading apple docs. Sure, the tone isn’t professional, but I don’t believe that is out of place.
Most of the author's frustration was due to lack of good feedback from Swift.
Like, how can it run a command that has an `async` main despite the fact that you didn't extend the async version of command?? That should've been an error (e.g. "bro, you cannot have an async main in this class, you need the Async version of this class which is called AsyncWhatever").
Not awaiting on an async function should be at least a warning. Another frustrating lack of feedback: it just lets you run it and nothing happens.
The version thing: it should show all possible variants in the enum, even the ones you should not be able to use, and then when you try using it, show an error saying "you need to change the version of this file to at least blah to use this". Why can't the Swift LSP do that? Apple has a trillion dollars, they can afford polishing their stuff.
The author is used to Rust, which would've made it very clear what was wrong in all cases.
Swift, being as modern as Rust, should be doing better than that. Languages that fail to give you proper error messages and warnings are just not worth it: just one of these "wtf is going on?" moments can cost you hours. Just use a better language if you can.
Swift ultimately is a language that is expected to be compiled by xcode. Package.swift isn’t even properly supported by Xcode still.
Way, 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.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".
Every library I have ever considered using and almost all of the ones that I onboarded have a "Quickstart" section. eg Guava, Guice,
My 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.netw...
Not 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/transl...
Tangentially 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
My 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-o...
The "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.
If 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.
For me the worst APIs by far are on Android. They are even worse than win32.
Nope, 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 :')
Agreed. 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.
Ever used the self-hosted BitBucket (formerly Stash) API?
Can anything be worse than Vulkan?
One 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.
In 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.
The difference is that most of those systems have documentation that explains how to use their weird APIs.
"The Unbearable Frustration of Figuring Out APIS... By Just Asking A Chatbot Instead Of Reading The Manual"
Unfortunately it's not like every API has a Fine Manual™.
If so, then you have Two Problems
This 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.
More 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.
It was my first taste of Swift, and has destroyed any lingering curiosity I had about it.
As 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!
Show me the incentive and I can likely guess how hard your API is to use.
I'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!
I like it. It tells me this wasn't written by AI
on 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.
That'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.
> You probably already know this, but apparently the first line in the file, that comment, is actually significant.
I did not knew this.
I 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.
Did 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).
I 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
Because 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.
Me neither, but it does explain why AI is so popular…