Comment by Salgat
4 hours 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...
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...
To be fair, Apple is known for having bad docs (for at least the past 5-10 years) that often don’t have examples or sample code, I think that’s more of an outlier.
I don’t regularly develop in swift, but when I have, I’ve been confused by the docs because they are so clearly auto generated (not LLM, just from the code) and sparse. Listing out constants is next to useless when they are confusingly named and have no description of what they mean or how the affect things.