ReadMe (YC W15) Creates Crisp Documentation for Developers Using Your APIs | Hacker News Reader

ReadMe (YC W15) Creates Crisp Documentation for Developers Using Your APIs

techcrunch.com

115 pointsgkoberger46 comments

This is somewhat hidden on the page:

> ReadMe was built almost entirely on Open Source projects, so we want to give back. If you're an open source project, shoot us an email and we'll upgrade you to the Developer Hub tier for free. It's the least we can do to give back.

Very cool.

We need to make that more apparent :) But yeah, email support@readme.io and we'll upgrade you for free!

Tried to email you and google bounced it. Turns out they have really obtuse policies for blacklists, and I can't figure out how to get my emails through. Any side channels to go through?

Try my username at gmail :)

I've had this happen to me a lot lately, and my assumption is that it has to do with my VPN – are you using a VPN?

Readme has been incredible for hosting documentation of our open source project (rbkit.readme.io). Very responsive to support requests, even though we weren't really a paying a customer.

We (https://commando.io) use ReadMe for our API documentation. Beautiful docs, created easily. Can't wait for automatic client lib generation and what the future holds for ReadMe. Here are our docs http://docs.commando.io to view what is possible.

Do they host the docs for you?

Honestly, it's disappointingly slow. Each page takes over a second to load. Your docs is one of those things that you can very easily cache heavily.

Yes ReadMe hosts. Absolutely agree, they need to implement full page caching, since the pages are basically static, and should not be rendered on each page load. This would be easily done with nginx, memcached, or redis.

Yeah, that's our fault. We have a new super-quick template coming out soon.

For those that want a lower-tech but scalable solution that can integrate easily with your build tool:

AWS S3, NGINX + AWS Signing Plugin + Basic Auth, reStructuredText, and CircleCI.

Very cheap, super easy to scale, and basic authentication for private. Use your own domain, have full control over the domains and which S3 buckets your route to, and use ReadTheDocs templates which are great for documentation.

https://dash.readme.io/login

Really love the animation here. Attention to detail matters.

@gkoberger I'm curious to know how long you estimate this took you to implement and how many people comment on it. I'd estimate < 15 minutes and hundreds of people. Am I close?

You're almost exactly correct! About 15 minutes, and we got almost 200k hits because of it. It was on Smashing Magazine, Little Big Details, and just about every designer I like tweeted about it. Totally worth the time it took :)

Those are incredible results. You'll never implement a feature with a better ROI :)

How does this compare to Swagger, Mashery, Apigee, etc?

We have Swagger support is (super early) beta; basically you can use your Swagger Spec right in ReadMe.

The focus is on more than just reference docs, though. ReadMe also has space for tutorials, topical guides, support, etc. And soon, we'll have things like onboarding flows and other things that customize the experience for each individual user.

As for Mashery and Apigee, features aside, last I checked, both start at about $10k/mo. They are more focused on API management; a "developer hub" is just a side effect for them.

Apigee just uses Drupal for their developer hub with some loose integrations into their api management (users, authentication keys, etc).

There's nothing I like more than some great API documentation. Seriously, whenever I see that the author of an API/library writes good documentation (and examples!), it improves the quality of open source software a lot.

This is a super cool startup and I love that you are giving back to the community.

Noticed a bug: If you click on "Custom CSS" in the Examples section, the description starts out awkwardly with just "to stand out?" In the markup that paragraph is enclosed in an element called <Looking>. Maybe a misplaced character in a template?

Fixed, thanks!

Few apps have impressed me as much as Readme.io. The attention to detail and beautiful yet functional UI are superb! It was a delight to create the docs for http://www.js-data.io with Readme.io.

Thanks so much for the kind words :)

We're using Swagger incorporated with Flask-Restful, which has been quite straightforward to setup and maintain. I like ReadMe, but I feel like it needs stronger integrations to be compelling - e.g. autogenerating code examples for various languages.

Both Swagger support and code generation are coming in the next release :)

Documentation is one of those very unsexy things that's so important but so many people and companies just tend to overlook. It's good to know there are companies aiming to fix this.

I'm a bit confused by the "use your own domain" option. I'm actively looking for a product with functionality like this, but it needs to be 100% self-hosted. "Use your own domain" suggests that ReadMe still handles data storage. Are there any fully self-hosted products that are similar to this?

Use your own domain is exactly how you interpreted it. There's nothing close to being equivalent, however there are a bunch of open source projects for documentation. Check out Swagger UI or Slate by TripIt.

Out of curiosity, what are your concerns about hosting documentation on a third-party site?

Our API docs need to be only available to authorized users. Due to the industry the API targets, self-hosting in a vetted secure environment is mandatory.

Feel free to use this template -> https://github.com/catalyzeio/HIPAA I made for our HIPAA docs. It uses middleman, slate, erb and sass. To password protect it you could use something like this -> https://github.com/agoragames/nginx-google-oauth

This approach to documentation works really well with netlify (https://www.netlify.com).

We let you link your middleman repository to a netlify site and instantly setup automated builds with continuous deployment to our CDN.

It's great for developer docs since you can let people submit pull requests for fixes or improvements, and we'll auto deploy when you merge them in.

@Mashape we're fan of Greg and Gabriel since long time now.

They have done an amazing work with very limited resources. If all you need is a Documentation w/ Support they are the faster/cheaper solution for you. And the GUI is details oriented, unlike other complex/heavy Enterprise solutions.

Thanks Augusto :)

I'd like to see it develop into a more generalized thing. Rather than offering nice looking docs, make it The Way to view docs for anything. Man/info pages 2.0 if you will. This should be to documentation what Github is to opensource.

Will you feel the same when when say, GitHub buys ReadMe and Oracle buys GitHub?

I actually wanted to say Github should buy and integrate it (if it went the direction I Imagine). But on a second thought you want to incentivize proprietary stuff to be on there too, so it would have to remain somewhat separate from core Github. And Oracle, haha. Oracle buying anything you like is scary :-D

I've got an internal API that isn't available for public consumption, but would enjoy having beautiful documentation. Does ReadMe have an option for that?

Of course! Many of our users use it internally. All plans have an option to make documentation internal: either by inviting collaborators, or a site-wide password.

Where's that option? I created a project, and the closest thing I could find was in Versions. I clicked on the "(?) Public" thing, and it said that I couldn't change it or something. I don't want it to be public, but it never changed to a yes or no option, just stayed the same orange with a question mark.

In the sidebar, called "Internal Documentation"

http://cl.ly/image/0L3P0S312u3X

using swagger and quite satisfied with it .

will be good if the OP points out some unique features that I am missing by not using ReadMe ?

Use case : Private / Internal API with less than 10 Devs .

They aren't necessarily incompatible. ReadMe will very soon support Swagger, and adds things like commenting, topical guides, code snippet generation, etc.

Any chance of being able to login with GitHub/BitBucket?

gkoberger is there a roadmap for this?

Hey Colin! I'm @gkoberger's cofounder. We don't have a published roadmap, but we're hard at work. First priority is to release a rewritten template that will accommodate larger, more sophisticated documentation projects (another level of subcategorization, multiple documentation sections within one project, better search). Then, we'll start tackling more automatic ways of consuming code and creating documentation. We're ambitious, stay tuned.

Url changed from http://blog.ycombinator.com/readme-yc-w15-creates-crisp-docu..., which points to this.

Reply on news.ycombinator.com