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.
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.
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
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."
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.
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.
> “All of this is written with a sense of anger and sarcastic invective that doesn't seem appropriate.”
Huh. The end of the piece says the author was “frustrated”. And throughout the author says things at the end of paragraphs like, _the result was an error x, but I already have/did x!_
I read the piece because I was curious about this description of “anger”. I relate to the journey as the author describes it—frustration. Though, there are a few “dramatic” words here and there. Not least of which is in the title, “unbearable”. But I usually mark that as a crutch in the personal Blog medium.
On a more pedagogical note, encountering a personal piece like this documenting a journey of idea to (near) success is an important genre of tech writing for one’s self and maybe others. As others have noted the OPs missteps, so too the OP, with hindsight, can revisit the piece and notice where they went wrong. If you’re away from the language/project for a while a piece like this is a good review before starting the next project.
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.
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.
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).
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.
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.
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.
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`.)
28 comments
[ 2.5 ms ] story [ 55.4 ms ] threadThat's how modern software industry feels like.
I did not knew this.
> ... I found mysekf launching TextEdit just to do that
I hope everyone else enjoys it!
> 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."
Huh. The end of the piece says the author was “frustrated”. And throughout the author says things at the end of paragraphs like, _the result was an error x, but I already have/did x!_
I read the piece because I was curious about this description of “anger”. I relate to the journey as the author describes it—frustration. Though, there are a few “dramatic” words here and there. Not least of which is in the title, “unbearable”. But I usually mark that as a crutch in the personal Blog medium.
On a more pedagogical note, encountering a personal piece like this documenting a journey of idea to (near) success is an important genre of tech writing for one’s self and maybe others. As others have noted the OPs missteps, so too the OP, with hindsight, can revisit the piece and notice where they went wrong. If you’re away from the language/project for a while a piece like this is a good review before starting the next project.
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.
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".
I've always loved Microsoft's API Browser for this reason: https://learn.microsoft.com/en-us/dotnet/api/system.net.netw...
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.
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...
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
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
Maybe English is another of the API frustrations that led to this screed.