I had this same experience. It wasn't until I pushed something live that those things/people just fell into place. Great article!
> I’m sorry to say we decided not to fund you. We liked you as individuals but we had a hard time seeing how developer API documentation was the right beachhead.
Perhaps I'm looking too much into it, it's just surprising to see, on the record, the polar opposite of what pg claimed on several occasions: people, not ideas. Or did I misunderstand it?
The OP says in his article: "Looking back, I never could have started a company without this [freelancing] experience."
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.
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.
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.
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.
You want these people on your team.
I never attended so I can't say if this is indicative or not of the school in general, but it's funny how much these first impressions completely changed my decision to apply!
I'm curious about "idea factories are a dime a dozen, and nobody would want to work for one". I've turned down similar arrangements in the past because they felt vaguely sketchy, but didn't realize "idea factories" are common. What are the problems with them?
* No incentive to see anything through, since there's always a "next idea"
* Lack of vision. Most of the good startups have someone with a general vision, which is impossible this way.
* Harder to recruit people since there's no core idea to get behind
* Since the only way these are funded is by a rich person (after all, no VC would ever invest in one), it's susceptible to the whims of said rich person.
* What happens if something becomes successful? How does equity/spinning out/etc work? And, if it spins out... all the revenue for the "factor" dries up.
* Well defined procedures for choosing what to work on and for how long
* Agreement on what metrics to to base go/no-go decisions for continuing with an idea past the initial stages
* Contracts to specify how spinoff equity is assigned. One interesting proposal I've heard involves a calculation based on developer hours worked over the initial development period.
I appreciate that this is hard (if possible) to do in practice, and that lack of vision might be a fundamental problem. It also feels like it could be an excuse to treat developers poorly -- which was one of my concerns when I had the opportunity and seems to have happened in this case.
I also have been pondering docs for many years and I agree with this statement. The core value I was going to build my solution around was by incorporating / generating examples from real code. Rather than being docs that were published it would almost be close to a code search engine. While the developers are lazy and rarely document you could bootstrap the documentation by finding example usage in the wild and presenting it and from there allow the users annotate it (and the developers if they ever get around to it).
There are many problems with todays docs, another one that is missing has to be analytics. If I own an API I want to know what users are constantly looking at and discussing so that I can make that part better, less confusing, etc. And conversely if there are no example usage and no one has ever looked at an API that would be useful to know too as it could be code that could be ripped out and no longer maintained. What api are users searching for, but never find? There is more, but these are just a few off the top of my head.
By generating content rather than relying on the developers to sign up and publish the site would explode in size and utility. Think Yahoo directory v.s. Google ala 1998.
The idea that someone would generate static html files and put them somewhere is almost barbaric compared to the richness that could be provided.
Unfortunately I don't really have a financial story to go with this idea. One was to be free for open source projects and charge for commercial. But honestly more likely would be that I would build it for a few years and then someone like Facebook would just call me up and buy it out to shut it down and solve their API documentation problems. Not saying that is bad, but I would have to make it until that would happen and I would prefer to have found another solution than a aquirehire end game.
This is very inspirational, and very true: the ideas I had years ago I could never have brought to life, and I probably would have failed, badly, at the business side. Today, I can bring things to life, and I'm understanding more and more of how businesses run.
That said, goals aren't plans, and five years is a reasonable time-horizon for a major goal. He did a lot of things right in his use of time, including giving it a go too early, and then again getting sucked in to a startup that didn't really work out. There is nothing like seeing things fail to teach you the elements of success.
Part of that use of time should definitely be asking yourself "Am I pursuing the right goal?" as you learn more, but a fair number of people get it right.
Don't use goals to measure "Success" per se but rather, yourself. It's a great lens to see trends in what is important to you in thought and practice and where they diverge.
Shoot me an email at greg@readme.io if you want to talk more
I'm curious as to the exact take-away here. The author seemed a bit naive. The investors approached him with a bad idea that has numerous potentials for conflicts of interest, and he gave in, believing verbal promises would eliminate those conflicts.
I would guess that if you want to get into the idea business, you should probably fund yourself using your own ideas and your own implementations. It's a pretty abstract business model, one that can very easily devolve into "we will do anything for anybody who will give us money". So you need a pretty strong vision and leadership skills to keep that from happening.
Goals and plans, especially 5 years in the future, can be hard to keep up with but the feeling of achievement at the end if truly amazing. I think even the practice of just sitting down and setting goals and making realistic plans goes a long way to helping you get there.
I just signed up for readme.io last night and it is an incredible product. The attention to detail is astounding. I've just become a big fan of yours. Never wait again. Your execution is too good.
Good luck,
Austen