📖 How is our API documentation?
Hey Devs of IH!
I'm working on Feather - where we're trying to build the world's simplest Auth solution (a basic React integration in 3 lines of code. Vue coming soon).
We just opened up our docs to the public, and are looking for feedback: https://feather.id/docs
What are your thoughts? Does the structure make sense? Are the docs simple and easy to understand? Or do they make you want to tear your hair out?
(The service is currently in private beta, but you can request access from the home page)
Appreciate it!
Phil
I like the look of it, but would echo the point on "And where is that 3 lines of code?" - that's what I'm looking for when I clicked!
I've just started putting together some API docs of my own using Gitbook. It's free for 1 user and I've been pretty impressed so far (here's my draft: https://docs.hyko.uk/).
Not suggesting you move away from building your own as it's looking good, but just incase you hadn't considered a 3rd party alternative 🙂
Out of interest what did you use for the scroll behaviour? It's real nice and snappy! 🦞
Hey, thanks for the feedback! It's all React under the hood. The automated scrolling is just a
<HashLink>from"react-router-hash-link" with asmooth` prop!E.g.
Note: From what I can tell, Chrome and Firefox recognize the smooth prop and will animate the scrolling, but Safari just jumps straight to the link.
Awesome thanks, that'll definitely come in handy! 🙌
That's great to triangulate feedback that the key thing people want is to see the 3 lines! We're prioritizing getting those into the spotlight - fast. Right now, we have a version in React that's 3 lines - and in Vue, should be similar
GitBook is really solid - we did give it a look! Ultimately, we didn't go with it because it's very opinionated with how it looks and we wanted lots of control with the styling.
I'm gonna have to tag @garfield to answer the question on scrolling! He's actually the chief builder on Feather (although I'm getting my commits up) and can answer all the details :D
Nice one, thanks! Good luck with it!
By the way, not sure if you saw this piece of documentation, but I thought it was particularly impressive, even by Stripe's standards
https://stripe.com/docs/payments/integration-builder
That is amazing. I had seen this, but I forgot it existed - we might want to have something exactly like this for our "3 line" demo!
Thanks for sharing your API documentation, the site looks polished and professional and the product is certainly intriguing.
What your documentation is missing is a "Getting Started" guide that shows the fastest way to get something done with your API. Right now there's a lot of material to read beforehand in "Core Concepts" which kind of goes against the simplicity that you want to sell your API with. The "Getting Started" should be the most prominent thing and it should explain how to get an API key, create a user and credential, and make an authenticated request. Only include what is absolutely necessary.
In the Developer Experience (DX) community there's this concept of "time to first hello world" as a metric for an API product, and I think it would be good to organize your documentation for that metric. Once the user has got the wow-effect of what they could achieve in a few minutes with ~ 3 lines of code they will be more intrigued to learn more and understand the theoretical concepts behind your product.
I love the concept of "time to first hello world"!!!
Really like your suggestion of focusing on a "Getting Started" guide - and we'll be optimizing around "time to first hello world" from now on - and a getting started guide is going to be our first attempt at this optimization.
Let me know when you've created the guide, I'll be happy to review it.
Hey Lukas - we've created a quickstart guide! It's not exactly 3 lines anymore (technically 9 lines), but would love some feedback
https://feather.id/docs/quickstart
Also updated our docs page: https://feather.id/docs
The new docs page is really great, it gives the starter guide the adequate presence and arranges everything else nicely below it.
The starter guide itself looks great, but there are some smaller issues. For example: "If no one is signed in, then display a sign-in form. Otherwise, just display the user's profile." This sentence leaves me wondering how I can do either of those things. Also: which fields are there in a user profile? Adding a small example and then linking the the respective sections in the references docs would be a great improvement.
Basic React integration with 3 lines of code - awesome! Might I suggest your landing page or documentation reveal those 3 lines :-)?
Haha yup, we've realized we've neglected to spotlight that - but we're working on it! Stay tuned :D
But overall we think Feather.id is a great idea. Not only is adding logins over AWS Cognito a huge pain but testing those logins is an almost equal hassle.
Thanks for the kind words! We had a similar experience with Auth0 and that really led us to believe there could be something a lot better.
Would love to chat about your experience with Cognito some time! I'll reach out ;)
This comment was deleted 5 years ago
Ah, yes this is good feedback!
We've taken inspiration from Stripe and put the API documentation under it's own section: https://feather.id/docs/api But I think that's just a layer that isn't super helpful
The "homepage" for our docs is definitely not ideal if couldn't keep reading it! And the fact that there is no obvious demonstration of the 3 lines is a good call out.
This comment was deleted 5 years ago
Those are some good links on line length - very helpful!
And haha no worries - I've learned over the years to separate "facts from stories" and the feedback you gave has lots of useful facts. Will take that over a generic "good job" any day (although "good job" + actionable criticism is the best package lol)
And if you do one day become a customer, you can expect us to be very welcoming of any future feedback you might have ;)