An API is only as good as its documentation
rocketeer.be
An API is only as good as its documentation
1–10 of 59 posts
Re: An API is only as good as its documentation
#2I have a corollary of sorts:
A framework is only as good as its UI.
This is a widely neglected point. Only game engines tend to understand this fully (e.g. Unreal Engine's editor). But Smalltalk and NextStep/Cocoa had a grasp of this too.
Even without a GUI, the interface matters. Rails' "generate" and "console" commands are a major part of its appeal.
Re: An API is only as good as its documentation
#3I wish we could have "documentation day" on github, where all project maintainers would spend one whole working day on documenting as much as they possibly can.
Re: An API is only as good as its documentation
#4I have a corollary of sorts: A framework is only as good as its UI. This is a widely neglected point. Only game engines tend to understand this fully (e.g. Unreal Engine's editor). But Smalltalk and NextStep/Cocoa had a grasp of this too. Even without a GUI, the interface matters. Rails' "generate" and "console" commands are a major part of its appeal.
Absolutely, tooling is a hugely important in making or breaking any programming language/framework.
In the end it all generalizes to "Your product is only as good as its experience".
Re: An API is only as good as its documentation
#5I'm currently working on a libre push notification service (Heavy WIP) and since this post is about API's and Documentation I was wondering if mine is any good.
It requires javascript for the "full experience". https://api.pushjet.io
Should I redo it? Are there things I should change?
Re: An API is only as good as its documentation
#6I wish we could have "documentation day" on github, where all project maintainers would spend one whole working day on documenting as much as they possibly can.
Not enough. Its more fun to create software, but documentation is the part that no one likes.
It is absolutely necessary, in particular when other work with your code.
And we have many stages of documentation: the project documentation (what is it, what does it, how, ...), the code doc, the rest-api doc. And it get really complex on further development. I think that is one reason for the small JS project explosion on npm / github of the last years.
Re: An API is only as good as its documentation
#7I'm currently working on a libre push notification service (Heavy WIP) and since this post is about API's and Documentation I was wondering if mine is any good. It requires javascript for the "full experience". https://api.pushjet.io Should I redo it? Are there things I should change?
Looks simple and good to me. However, on first glance, it's missing some quickstart guide/introduction and how to authenticate. Also, some calls seems to return nothing at all, is that correct?
Re: An API is only as good as its documentation
#8I'm currently working on a libre push notification service (Heavy WIP) and since this post is about API's and Documentation I was wondering if mine is any good. It requires javascript for the "full experience". https://api.pushjet.io Should I redo it? Are there things I should change?
Looks simple and good to me. However, on first glance, it's missing some quickstart guide/introduction and how to authenticate. Also, some calls seems to return nothing at all, is that correct?
I've written a draft for a quick start guide using python/javascript (code with comments). I've been withholding publishing it because it's not fully done yet and message queues and the android app (only thing to do is the Matrial UI) are my #1 priority at the moment.
One of the main ideas behind the service is that there is no authentication. You just generate a persistent UUID and use that.
Re: An API is only as good as its documentation
#9I'm working on integrating Braintree payments into a client of mine. Braintree is a perfect example of this and is a wolf in sheep's clothing, meaning, their docs look great at first glance until you need to get all the way through them.
For example, you start reading about how to do A. Half way through, you find out you need to do B. So you look at the link to B which then refers to C but C is A and you realize you're in a loop.
So then you try their search function, or Google, but then you find yourself linked to either outdated docs that look like the same thing or articles about the subject which give no detail.
It's spaghetti documentation mixed with out of date spaghetti mixed with meatballs. At this moment, I have 13 tabs open to various parts of the docs trying to piece things together to understand how to make it work and, sometimes, I find the out of date docs more understandable!
Re: An API is only as good as its documentation
#10I'm currently working on a libre push notification service (Heavy WIP) and since this post is about API's and Documentation I was wondering if mine is any good. It requires javascript for the "full experience". https://api.pushjet.io Should I redo it? Are there things I should change?
I would add a few paragraphs introducing it and giving some common examples/use cases.
I like your "try-this-request", however IMHO it is missing a "request is in progress..." kind of indicator - clear the output space and add a spinner? I had to look in the developer tools to ensure that it works.
Finally, not all things work: 'Websockets/Run Example' doesn't do anything. In the background there is a 500: 'WebSocket connection to 'wss://api.pushjet.io/socket' failed: Error during WebSocket handshake: Unexpected response code: 500'. In your defense, you do mention that "Websockets are really iffy at the the moment and are currently in the process of being redone". But still, better capture that error and show it somehow.
All in all, ahead of the curve ;) Some UI lovin' would put you at the head of it.