Hacker News new | past | comments | ask | show | jobs | submit login
Show HN: ReadMe.io – Beautiful Documentation Made Easy (readme.io)
266 points by gkoberger on Oct 7, 2014 | hide | past | favorite | 79 comments



Hey all, founder here! I've worked at a bunch of startups, and inevitably we'd have to make a dev.startup.com and I'd wonder why we were re-inventing the wheel each time. Every startup needs this, they all have the same basic features, yet every startup has to do it themselves.

Ergo, ReadMe! I wanted to do more than just documentation; it's a full developer hub for your community. The goal is to make it so any startup can have beautiful, interactive, collaborative, Stripe-quality docs without wasting valuable time.

HN has been a huge help while building it – I even picked the name after finding the domain for sale on HN :)


Congrats Greg for your first product! At least it looks fantastic! I haven't tried it properly yet. But I hope to see many more awesome things like ReadMe in the future.

And I am amazed to see that you guys pulled it off with the living in a different country bit. Amazing! :)


How many people do you have working on the product? It's beautiful and I love how fast it's progressing.


I'm the developer/designer, and gdillon is doing everything non-technical!


Looks great. Wish there was a plan for opensource projects, which allowed me to use customized landing page etc.


E-mail me (support@readme.io); we'll hook you up :)


Just tried to learn about your product... I was, and still am, completely confused about what it does and why I need it...


readme looks awesome.

What made you set the free trial to "till you launch" ? Don't you think some would use it for internal docs for there own reference or am i missing something ?


Got the suggestion from Danny at StatusPage.io. We really wanted people to be able to try everything out without needing a credit card or feeling pressure.

The "upgrade!" alerts get more and more naggy if the system detects you're cheating and using it for internal use :)


Love the attention to details, like the focus event on the password field: https://dash.readme.io/login


I know! This just makes me want to hug something!


Heap Analytics is in the process of moving over our documentation to ReadMe.io and so far the process has been amazing.

The ReadMe team is really responsive and helpful, the documentation is beautiful and the interface goes above and beyond.

Just to give you an idea of how polished the service is, if you select a background color that contrasts poorly with the text, the interface will let you know. It also automatically generates a "white" logo for darker pages. This has almost nothing to do with writing documentation, but has a lot to do with making documents readable for users, which is easy to overlook if you're not a designer.

See our docs: http://docs.heapanalytics.com/

Right now they are a transcription from http://heapanalytics.com/docs but we're planning more robust docs and ReadMe will make that process a lot smoother.


[deleted]


This came up when we were working on this, the team at ReadMe has been very responsive about this and I don't feel like we'll be trapped on the platform. They use Markdown for almost everything except some widgets, and since I'm going to use mainly Markdown I don't feel locked in.

I also feel confident that if I kindly asked for the contents of my site, the team at ReadMe would send it on over in what ever way they could. That may change in a year, but I doubt it, if anything, I bet they'll have a more automated way to get content in and out.

The ToS sounds pretty standard for "content" sites... that is, they have to have the rights to display the content, since they are the host. In my experience you're much more likely to get a shady crawler copying your content and reposting it than the service you pay using it in ways you didn't expect.

edit: woops you deleted. I think your questions were very valid, so I'll leave my reply :)


Sorry about that. I thought it sounded negative and didn't want to talk badly about the product.

My question was basically "Are you okay with publishing content on a site that owns the content?"

I imagine they are building export tools in the future, and this is just the first version.


I don't think it was negative, that's exactly the kind of question my co-workers asked when we were talking about ReadMe.

I'm OK with it. I've found that more often than not, questionable third parties skimming content and republishing outside any control tend to steal your content and misuse it more than providers that have a solid service do. I trust the ReadMe team to do the right thing and if they don't, instead of leaving supportive comments on Hacker News, I'll rant :)


"ReadMe has made our lives infinitely easier. We've had it on our todo list for over a year, and a day after finding ReadMe we had our docs launched. We're super impressed. You guys have built a fucking awesome tool."

I don't know, but having swearing on a professional website is probably not the best way to go. Looks like a nice startup though.


We debated about this a lot. Jesse wrote to us via our Olark plugin, so there was a back-and-forth – he didn't just start swearing. He was one of our first customers, and having someone we didn't know love our product was awesome.

We liked how enthusiastic and genuine it sounded, and I've personally never liked when people type "f*cking" (we're all adults; that asterisk isn't tricking anyone.). But alas, we've removed it for now :)


    I usually type fuck*ng or m*therfucking.
EDIT: OH MY GOD HOW DO YOU TYPE A FUCKING ASTERISK


If you only have a single aster*sk in your comment, it doesn't get converted to an emphasis.


Could've changed it to "friggin'" for the PC folk who get appalled by casualness. That's what I usually do when I'm unsure of how stiff is the other party.


I'm not in any way opposed to vulgarity in general, but I have to admit that this stuck out to me too. Not really necessary.

(Though my first thought wasn't "Who puts 'fucking' in their testimonials section," it was "Who puts 'fucking' in a business email to a new vendor?")


It's a word. Specifically, its a word indicating magnitude. I'm not bothered by such words.


to be fair the people who get appalled by reading the f-word are probably not the target customer. who drops f-word all the time? programmers, entrepreneurs, designers, developers, managers. certainly not established 100 year old corporation, but most certainly the hip, fast moving, horny, 20~30 something olds who eat and breathe technology.


Personally I find the "hip" use of curse words a red flag for working with a company.

If you can't even be professional on your external-facing site, it's a certainty that I'll have to put up with much worse unprofessionalism in our closer business relationship.

But that's just me, and I don't pretend to be in the majority among the HN/reddit crowd.


More like insecure, inarticulate brogrammers who are getting burnt out overworking but think it's cool. I don't find swearing to be a conducive way of creating an inclusive, thoughtful work environment. I had enough of this fucking bullshit in college. Time to grow the fuck up.


Now that I re-read my comment, what I actually meant to say is - I had enough bravado swearing by young people in college, and it is time to grow up and act professionally - but now I realize the comment can be read to mean that I had enough of non-swearing PC behavior in college, and it's ok to swear as an adult at work. Interestingly; I stay at an equilibrium of points after roughly equal upvotes and downvotes. I wonder if it would've swung -- or ++ if the meaning was universally conveyed correctly by me.


Okay now I can't tell if you're serious due to the last two fucking sentences.


Genuinely curious if your comment is meant to be ironic?


Hey, I'm one of those, I think! For me, dropping a few in a conversation is one thing. Seeing it chiseled onto a web page is quite another.


Agreed. Would you want to see that your doctor's written stuff like that in your chart (e.g., "Patient's got some really fucking bad gout!")? No? Then maybe it's unprofessional.


I'm pretty sure comparing the addition of 'fucking' as a crass emphasis on the seriousness of someone's medical condition, with saying it excitedly when happy about a product or service you're enjoying, is drawing a flagrantly false equivalence. But heck (fuck?), that's just a reasoned, logical, non-PC take on this - three things that are sadly absent from much of the population these days.


Okay. "Patient's cancer is in fucking remission!", said excitedly and happily is nevertheless possibly indicative of generally unprofessional behavior, which was quite obviously the point. But I guess discussions bereft of pedantry and hubris are sadly absent among the HN population these days.

None of us is personally offended by this language. We simply understand that it has no place in professional communications, because it can only really harm perception vis-a-vis just leaving it out and so probably isn't a smart business move.


This looks nice but $60/mo seems incredibly pricey when there are also nice, and similar, open source solutions such as http://ricostacruz.com/flatdoc/

What extra value am I paying for?


Talking from the perspective of a startup person - 60 dollars is less than an hour of dev pay. It seems to me incredibly cheap. I often worry that SaaS startups undercharge and starve themselves out of stability & growth.

We've spent a lot of time putting together our API docs and it's nowhere as nice as this. The service they're providing is valuable to me as a way of solving this problem. I've never met or even heard of anyone working at readme.io btw - saw this on HN for the first time today.


I use ReadMe, and I haven't used flatdoc, so correct me if I make an assumption about what it does.

A huge benefit of ReadMe is the document organization and drafting capabilities. I no longer have a bunch of Dropbox folders that I save Byword Markdown docs to.

I can organize things in a reasonably sane way, and when I am writing new docs (think of docs as a living organism) I can write them in ReadMe and decide when and how to publish them.

It removes a lot of duct tape and glue compared to other solutions I have looked at.

I think if your aim is to crank out a few pages of Markdown and host them on a static site generator, other options might be good for you. ReadMe is definitely first class if you want to create a corpus, and present it beautifully without a bunch of extra steps.


It saves a lot of developer time, you would just have to write the docs in markdown, not have to worry about the layout, hosting or building another app just to manage your docs. IMO it provides a lot of value for money. You could always just use the free plan and then upgrade later. With markdown files, you wouldn't really get locked into the platform.


As far as I see, Readme.io has additional features but everything you've listed is available for free on readthedocs.org, built on Sphinx which is free software.


Why should they not coexist? Some want it for free and some want to pay for e.g. support or additional features.

Last time i watch at RTD it was a plain .md project import from e.g. GitHub only to show a plain documentation.

In Readme.io you can edit/write your docs, have blog function and an integrated discussion plattform (for support your users). If you not need this features, you can use RTD or directly sphinx.


We just released our API on apiary (http://docs.commando.apiary.io), but after finding ReadMe.io on ProductHunt, we signed up for a paid plan that very day, and are in the process of migrating over.

Our focus for our API documentation is beautifully designed and easy to read. All the extra features of Apiary and Mashup such as proxying, rate limiting, billing, and mocking requests are not really a priority for us. ReadMe.io is a perfect fit.


What made you decide to get a paid plan instead of the free plan?


Mainly, we are a startup ourself, and we know how much blood sweat and tears goes into it. ReadMe.io provides us a lot of value, and thus we want to pay to make sure that value stays around. Also, using our own domain is nice. :-)


The most important feature for documentation is /a really good/ search. I can't see anything about searching on the site? Can you clarify?

IMO everybody should use https://readthedocs.org/ for documentation since all the docs will be put into elasticsearch (backed by Rackspace FYI) and the results when searching are of really good quality.


Agreed! ReadMe does search, with the added benefit of also searching user questions, blog posts and errors.


This seems highly dependent on Javascript for displaying its (actually static) content. As someone who likes his notebook fan to stay calm and not have websites shove obnoxious things into her face and thus browses with JS off by default, please do not require Javascript to read your documentation. JS is nice for animations or truly dynamic content, but why require it for static things like this?


I am just guessing, but the site uses CodeMirror (JS) to do syntax highlighting.


Check out the examples, they load content via JS.


Oh sorry, you meant why does it use JS to load content and not why it uses JS at all.



Love it and agree it's beautiful, but as a startup, I disagree with the "it's just 1hr dev a month" in cost. Setting up something from GitHub onto Heroku or similar costs me about 2 hours (if that), ever. And if it can be updated without too much of a pain, it's hardly going to take >1hr of dev work to maintain the project (update the docs perhaps...but you'll need to take the time to do that regardless).

I totally also agree with the sentiment that people don't pay what most SaaS apps are worth. We save users 3-6 hours per month and charge $13 for the privilege, but even then people frequently complain about pricing (can't please everyone).

Just my 2c. Love the concept and could see myself using it, but the price point is just too much beyond free, compared to DIYing....but I'm an open source person, so that could just be internal biases.


We've been using Readme.io for our documentation for a while now (http://api.knowtify.io). Love the team, but mostly I love that the non-technical folks (ie - me) can maintain/update our API docs without engineering having to time on it. It's one of the last things engineers want to spend time on (and one of the last things I'd want them to spend time on)...


Mozilla is also using ReadMe for Brick: http://brick.mozilla.io/


Really well done product. Using it for my site now.

What are the future plans for making this into a developer hub?


Thanks Frank!

We've already built out a bunch of community features to make it more than "just docs", but we have a lot of things we're really excited about.

We want to do things like have an "application dashboard" (where users can manage API keys), some basic (optional!) API management, onboarding "wizard" and more – the whole developer experience should be cohesive.


Will I be able to export my docs? I'm not really willing to put my docs on readme.io without knowing I can export all my work if you all go under. I'm currently an Apiary for Companies subscriber and value that feature but, prefer your design.


Yup! There's an Export Docs button on the settings page.


We (StatusPage.io) are also in the process of getting our docs switched over. Greg helped out with the initial migration which was awesome. Definitely recommend other SaaS companies have a look.


Looks awesome. I am currently using Swagger to document a REST API. can I import from the popular Swagger format ( YML) to your platform ?


Swagger is on the short-term roadmap! In the slightly shorter future (AKA it's working now, although we disabled it for new signups due to overload), we support apidocjs.com


This looks very nice.

Since you mentioned Swagger--We've started using API Blueprint for internal API design and collaboration. Do you have any plans to support importing from API Blueprint?


I've seen a couple of these projects lately. They are really cool and I see the need.

What seems to be missing (and is a no-brainer in my opinion) are auto-generated client libraries. It seems like you could easily create Ruby, Python, and PHP libraries if you know their API endpoints, methods and parameters. At the very least, you could create a starting point for them.


100% agreed. I wanted to get that feature done for the HN launch, but it didn't make the cut.

We have a lot of APIs using us now, so we're going to revamp our API endpoint builder with our new knowledge, and this will be a huge part of it. Check back in about a week :)


The code blocks are really something else in terms of looks. Is that a custom look, or is it some open source plugin?


Custom! We spent a ton of time on the "documentation builder", since we wanted it to be as painless as possible to write documentation.


What's so special about it? Where can I see an example?


Here's a screenshot if you don't want to sign up (although signing up is pretty painless and completely free :) )

http://cl.ly/image/020W0r1x3J1n


I suggest you guys to host documentations of some major free software projects. It benefits both you and them. They get nice documentation, you guys get some attention.

Edit: Feel free to contact me if you like the idea and would like to do it for KDE project. I'm a minor contributor and I might be able to ease the process.


Hey, I'm on the ReadMe team: We love open source. We've started working with a few great projects already. Check out the Ghost.org documentation (and reach out to their CTO, Hannah, she's great!) and the Brick by Mozilla docs are linked elsewhere in this thread. There are a few more that have yet to launch. Shoot support@readme.io a note if you'd like to get KDE started.


How does this connect to an API? Does it read Swagger? Or is all the setup (paths, parameters, etc) done manually?


Currently, you can do it manually or using http://apidocjs.com. (The latter is disabled for new accounts due to heavy load; will be back this week.)

Swagger (and a few other even cooler options) are on their way!


Creator of apiDoc here.... really nice that you use apiDoc :-)

I really like your nice and clean template.

A similar project was in my mind since i create apiDoc, but due the lack of time i am happy now that you create such a project.

Will link to your site soon, so that apiDoc users can see your good alternative for creating and hosting a documentation.


Awesome! I looked at a lot of "standards" (Blueprint, RAML, etc), and yours was the first that felt right.

I'd love to talk more! My email is greg@readme.io. Awesome work on apiDoc; it's been great.


Swagger would be great. Make sure that you can regen the docs without losing anything when the Swagger spec changes.

What are the cooler options?

(Also, the Blog link in your main menu on the home page 404s)


Reminds me of Manula http://www.manula.com/ which makes something that looks like this. And has been around for 2 years (since 2012). There aren't many solutions that tackle this problem, so keep up the great work!


Wow, wasn't expecting all the HN discount graphics on the site. I guess you either (1) are really fast at updating your UI and pricing, or were (2) really counting on this getting upvoted into the HN main page.


I am currently working on improving the documentation for Conda, Bokeh, Numba, and a bunch of other scipy-related tools. This looks pretty spiffy. How hard is it to import existing documentation?


Your example page is kinda busted when scrolling horizontally. (on Chrome 37)

http://imgur.com/HmzC1v0

Looks good otherwise though.


This looks awesome. I can't wait to start using it!


This looks beautiful and I have been testing your product yesterday and today. I have the following suggestions, which if implemented would convert the company I work for to your product. :)

1. Saving Basic Auth credentials so the user doesn't have to paste it in each time they test an endpoint.

2. A way to automatically populate the request form fields by clicking on an example request.

Keep it up; all my colleagues think it's a beautiful and well done tool.


1. Will be done ASAP! (the multiple alerts is a huge pain)

2. Same

Shoot me an email (support@readme.io) and I'll keep you updated on the progress of these two features. And in the meantime, I'd love to pick your brain on your use-case.




Consider applying for YC's W25 batch! Applications are open till Nov 12.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: