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

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

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

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.

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.

For me the worst APIs by far are on Android. They are even worse than win32.

"The Unbearable Frustration of Figuring Out APIS... By Just Asking A Chatbot Instead Of Reading The Manual"

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.

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!

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