Hacker News new | ask | show | jobs
by dmak 4107 days ago
This is a bit of a tangent, but I really wanted to comment on the product he is making.

I have been using apiary.io, and I always felt that it was lacking in many aspects (versioning, ghetto note editor, parsing issues in the preview, etc...). I just discovered readme.io and played with it briefly and it has solved every issue that I had with apiary.io. I will definitely migrate over, but having to re-do all the documentation from ground up is a bit of a pain.
3 comments
specialk 4107 days ago
I'm also an apiary.io user. I must agree there is something lacking in the hosted API docs space. What I find most lacking from apiary.io is features. They have such a limited way of expecting APIs to behave that it can be hard to represent some things inside the API docs system they have.

I wonder is it is possible to create an apiary.io to readme.io auto-migration tool. Even if it does require me copying the markdown behind the apiary.io docs manually into some tool that spits docs into readme.io. That would honestly save me many hours, probably many hours for many folk too.

I've requested access to the open source pricing plan, after I hopefully get approved it is probably something I'll look into in more detail. I'm in need of a new (probably) needless automation side-project.

Edit: wow I completely missed the free trail. If you're an open source project they'll upgrade you to the Dev Hub pricing plan. Ugh feeling so stupid for missing that the first time around and not getting started 10 minutes ago.

link
zzen 4106 days ago
(disclaimer: I'm the founder of Apiary) First things first - Readme.io is a great product and congratulations to Gregory for following his dream. I did so with my own, similar passion a couple years ago.

That passion was connecting developers - API builders & users. Documentation is just a part of this (interaction, collaboration, prototyping, and testing being others), which is why it’s a bit harder to be completely free-form. That said, we're aware that there's a lot room for improvement and we're working very hard to make Apiary better. Your feedback is really appreciated, I'd like to know more. @dmak, @special and @sidi would love if you could contact to me directly at jakub@apiary.io.  Thanks for speaking out and pushing us to improve.

link
sidi 4107 days ago
We have had a very similar experience, and I was a paying customer the first day they launched. However, over the month of migrating documentation - we discovered a couple of areas really lacking:

1. Having to use JS too often and they only offered it in their higher plans,

2. surprisingly poor md support. I don't usually write markdown in visual blocks.

In the end, we built an aggregation of open-source tools to create something similar to the effect of readme - https://github.com/appbaseio/docbase. It uses github for markdown editing and versioning, flatdoc for rendering docs, and creates a beautiful single page routing for the doc. http://docs.appbase.io is using it.

link