Great project but lack of documentation

[blackrosezy]

This is a great project but it was released too early without a proper documentation. Don't get me wrong, I like people contribute to open source. But without a proper documentation, it is useless.

Ever heard about Laravel? Yes, almost all PHP web developers knows about it. The author is Taylor Otwell, a very disciplined programmer. Here is a quote from his blog:

I promised myself never to release Laravel until I had great documentation, and I never release a new version until the documentation is totally up to date. Any PHP programmer can pick up Laravel and start using it in a matter of minutes. The expressiveness of the code itself and the great documentation truly make coding enjoyable.

http://taylorotwell.tumblr.com/post/21038245018/why-laravel

But in the end, this is your code. It is up to you to do anything with it. Just my two cents.

Cheers. :)

[rainycape]

Hi @blackrosezy,

I appreciate you being sincere. The problem with the approach you suggest is that, I can assure you, that way Gondola would have never been released. We're a small 2-man company and documenting the framework doesn't put food on the table, so we have to either do that in our spare time - which is incredibly rare - or take away from our billable hours - which kinda sucks. We write iOS, Mac, Android and WP apps, we write websites and we do all those things for both our own products as well as for 3rd parties. I'm sure you understand that's a lot of work and each one of us spends more time in front of the computer than anyone should.

While I totally agree with you that the documentation right now is lacking, I don't think the framework is useless because of that. There are a couple of tutorials to get started, some packages are more than properly documented (see the list at http://gondolaweb.com/doc/) and there are also example sites, like https://github.com/rainycape/gondolaweb and the soon-to-be-released gopkgs.com (which is more complex, uses the ORM, etc...). And all the source is there for everyone to see (which is rough and time-consuming, but it works).

Of course, the framework still needs more documentation, that's why we chose 0.90 as the initial release number. And you can be sure everything will be properly documented before we stamp a 1.0 into it.

If you're the type of developer which needs very detailed documentation, tutorials, examples, etc... I would suggest you bookmark Gondola and look back at it in a couple of months. I'm sure we will have way more documentation by that point.

[netpoetica]

I think "useless" is a pretty heavy term that really doesn't apply here :-) this project is pretty monstrous @ 500k+ lines of code, and seems to take into account solutions for a good deal of problems that most people who are just doing basic websites don't realize they have until the company they work for doesn't exist anymore :)

I would say, right of the bat, a couple of suggestions for improving the documentation initially, in order of how important I think they are:

1. Author/Organization Philosophy. What problems were you trying to solve? Why didn't another framework work for you? What is Gondola best at? What is it not best at?
2. More detail about the CLI (gondola command). Right away, explain whether it must be used (requirement), or how to work manually without it. Provide a comprehensive list of commands and their intended use - I looked through the API documentation (not tutorials) to find this and couldn't come up with one.
3. Make "Getting Started" more accesible. Instead of "Tutorials" and "Articles" being top level nav items in that dropdown, I recommend that when the drop down opens, the links are in this order: "Installation", "Getting Started", "Tutorials" and then Articles. You want the "Getting started" page to be as few clicks away for any newbie who is stoked to just get this up and running without making any investment in reading the code :) eventually those people are probably the ones who will write tutorials, documentation, and build the community.

Cheers! I'm looking forward to getting a chance to mess around with this project, very cool stuff