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".
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
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.
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.
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.
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.
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.
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".
> 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."
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
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.
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.
Edit: Come to think of it, both are made by Google :')
> ... I found mysekf launching TextEdit just to do that
I hope everyone else enjoys it!
on the other hand, I appreciated knowing that it was actually written by a frustrated human, and not sanitized by the Ghost.
I did not knew this.