B
Story
The Unbearable Frustration of Figuring Out APIs
  • Salgat
  • ·
  • 5 minutes ago
  • ·
  • [ - ]
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...

  • nabbed
  • ·
  • 59 minutes ago
  • ·
  • [ - ]
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

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

  • dvh
  • ·
  • 2 hours ago
  • ·
  • [ - ]
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.
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.
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!

  • otikik
  • ·
  • 53 minutes ago
  • ·
  • [ - ]
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.

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.
  • Svoka
  • ·
  • 2 hours ago
  • ·
  • [ - ]
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.
It was my first taste of Swift, and has destroyed any lingering curiosity I had about it.
Show me the incentive and I can likely guess how hard your API is to use.
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.
  • a1o
  • ·
  • 2 hours ago
  • ·
  • [ - ]
> You probably already know this, but apparently the first line in the file, that comment, is actually significant.

I did not knew this.