OpenAPI is making some headway in this area, although its hard to get everyone to standardize around _something_. Especially after people have gone through so many different documentation types such as RAML, Apiary, and others.
Because there’s no penalty or cost, and little to no competitive advantage. Only programmers ever see API documentation, and they are not in a position to force better documentation. If good API documentation provides a competitive advantage companies will pay attention to it. Until then they will continue to concentrate on dark mode and emojis.
Depends on the service. If the company sells to developers, or requires developers to extend their customer base (e.g. Stripe) they will put more effort in. If developers seem incidental to their service and customers they may not (e.g. Zoom, Google Drive).
What about SQL? Not even that has a solid standard; Oracle, Postgres, MySQL... Nothing is compatible!
How can we make a standard for something every company has different when we can't even make a standard for databases used by everyone.
He was talking about docs. JSON's is great, I was trying to make some guys understand and error on the syntax of a pretty big financial institution and after a couple of mails I just send them on of the pictures from the JSON docs and they got what they were doing wrong. The picture was just a diagram of how the parser works
So I work with this field and evangelize OpenAPI at work. The simple fact is, very few developers actually know about it, and the pool of online tutorials that don’t mention it so vast, I think it becomes a problem of scale and knowledge. Some companies use it, VMWare for example uses it for the fusion API documentation. But it’s 100% dependent on having at least a few devs at whatever company who have enough power to push for this as important