An API is only as good as its documentation

I find all of the auto-generated systems produce barely sufficient documentation.

Real documentation is written by a person who understands how to use the API.

Unfortunately, such documentation then suffers bit-rot if it's not updated whenever the API is updated.

What I would like to see is some way to describe an API which can be merged with the hand-written narrative and instructions, and can be refreshed whenever the implementation changes.

I don't think this is about being a Blub programmer. Rails is a complex web framework that is designed to help solve many common problems in web development. Therefore, it has tons of code organized in an arcane way you won't understand until you know what problems it's trying to solve.

That's why I always found teaching RoR (or equivalent frameworks in your language of choice) to beginners completely backwards. What the newcomer learns is how to tweak this huge blob of arcane magic here and there, and gains almost zero actual understanding of how things work. My preferred way of teaching webdev is showing how text goes from server to browser, how the browser parses it to render a page, and how a programming language is used to generate such text. And then I build up from this base. Sure, this approach won't make one a Rockstar Full-Stack Code Ninja in half a week, but at least the student has some solid foundation of understanding to work from and can comprehend why Rails looks the way it looks.

It also seems to me that the current trend in web development is people using huge complex tools, of which they need 1% and understand 0.1%, and thus generating layers upon layers of bloat. But my opinion here is probably biased as I hate webdev more and more with every single day I spend working in it.

The irony of this statement

"At Ticketmatic, we promise that anything you can do through the user interface is also available via the API."

in the context of the article is amusing. Going to the website, I find no mention of an API anywhere. I can only guess that it's API documentation hidden behind a login. This is the worst kind of API documentation. I've dealt with APIs like this far too often to find it friendly. In every case, it's been frustration.

Regardless, while the platitude is agreeable, this is literally an article that says nothing more than what fit into a tweet.

It all depends on what kind of API you're building. If you're implementing a RESTful API, no documentation is needed, as it is "surfable" due to the use of hyperlinks. If you're implemeting an RPC API (which is what most of us are doing), good and up-to-date documentation is key, as we need to document each and every meaningful end-point.

(Author here)

Nope, that's the old one for V2 (which isn't very good).

We're currently releasing the third generation of the Ticketmatic platform, where one of the big efforts is in improving the developer story.

That's not public yet, for which I apologise. There will be a beautiful developer program soon.

I didn't think that the article should wait on that. It's the idea that matters and didn't want any discussion to turn into a nitpicking over what we did right (and wrong).

This article mostly came out of a frustration with bad API documentation and I was hoping to inspire people to do (slightly) better.