If you take away how this looks, and start digging into the project from a beginner's perspective, this project is awful. I find this with most of the supposed "UI frameworks" out there for HTML. With a few exceptions, they mostly lack:
1. Good documentation that doesn't just define the framework, but teaches you how to use it and get stuff done with it. Code already defines what it is, your docs should tell me why it's this way and how to use it. In Kendo UI they've got a list of dependencies for javascript projects they need, then a few code snippets with no explanation as to why or how they work.
2. Good sample code, in a full complete project you can download, with documentation on getting it up and running. Your first sample code is how everyone will write code using your project. If you've got bad samples, poor formatting, and weird file layouts (or none), then that's what everyone will write and that's what you'll be known for.
3. Examples that gradually increase in complexity. Start off with a simple hello world, graduate to a chat app or something simple, and get them to a full blown large application. In this Kendo example they've got a demo picture viewer, with no explanation for how it was built, and viewing the source it looks like a huge mess.
4. Humor. These kinds of documentation are boring as hell, especially if you're just defining everything. It doesn't have to be insanely hilarious, but at least throw a few little funny tidbits in the code. Even the great tech books of our time have tiny little jokes for the people who pay attention.
5. Finally, these frameworks rarely have a "theme". MVC is a theme. Convention over configuration is a theme. There's only one way to do it. There's more than one way to do it. Themes work to help people keep the script for why everything works the way it does in their head.
It's too bad because this looks really good, and it could be the most awesome thing on the planet. But if I can't figure it out even if I want to, then I'm never going to try.
Finally, none of what I wrote above applies if your project is for fun and not meant to be a "product".
I agree with your points. Tutorial-style documentation is a way to go.
The main problem this framework has isn't its reference-style documentation (if a framework looks good enough I'm willing to do some extra work figuring out how to use it). Kendo's real problem is its licence. Apart from seeing how "awesome" it is you can't do shit with it.
Read the FAQ, the beta version has a different license than the full release will:
Q: How is Kendo UI licensed? Is it open source?
Kendo UI is dual-licensed, Commercial and Open Source (GPLv3).
The Commercial license includes full source, professional support, access to the latest Kendo UI hotfix builds, and priority influence on the Kendo UI roadmap. During the Beta phase, the framework is licensed under a Beta license and no commercial license is available.
1. Grant. Telerik hereby grants to you, and you accept, a non–exclusive, non–transferable license to install and use the Software for evaluation purposes only, solely as authorized below. ....
I must admit that I haven't checked your list against the Kendo UI. However +1 for a nice description of how to present a framework to potential new users.
Good lineup. However, I think that #4 is only appropriate in beginner's guides—docs always should have some boring reference section with quick navigation. HTML5 boilerplate lacks that. Jokes get old fast.
Perhaps some good examples should be mentioned… I think, SproutCore handles points 1-3 very well (http://guides.sproutcore.com/), but lacks #5 a bit. Django's documentation seems to have most of these, too. (These aren't HTML UI frameworks, however.)
Sproutcore fails on another point though with making too much "improvements" on version 2.x. Why would anyone consider using sproutcore 1.x if it's already deprecated, and version 2.x is far from ready, as well as the docs. The sproutcore demos doesn't even work. You gotta have working demoes. There's no excuse for that - try getting your boss to accept a framework with no working demoes.
If you don't manage to get a home run with version 1.x just stick with it and fix the damn bugs, instead of doing the big rewrite, with the promise that it'll eventually work. It'll just work if you stick with it and fix the last 10%.
Hm.
If you look --> in the documentation <-- you find your first protest invalid. And in those docs you will find plenty of sample code, for your second protest, and examples (#3) to go with them (what is sample code if not an example?). #4 Protest too much? #5 Does a framework's theme need a template, too, or will a motif do?
And other pages that are just enumerations of things that are in the code, then you've just defined it, you haven't told me how to use it or why it works the way it does.
Instead, they'd need docs that lead the user through step-by-step breakdowns of where things are, why they are there, how to exactly build an app from nothing, and get it working. They've got none of that. Just a .zip with some crap in it and nothing that says what to do.
Then, your idea of "sample code" is a couple of blocks of js on an HTML page? Right, I need HTML, Js, server setups, everything needed to get it working. If I don't have that then you've skipped over a ton of shared knowledge I don't have and that you need to take out of your brain and lay down so I can follow along.
"Protest too much?" You're a dick. Seriously, I love you guys who come in talking all tough like you're so damn right and really you just pedantically split hairs then throw out ad hominem attacks while claiming you abhor them.
But, then again, like I give a fuck what you think. The people who will actually benefit from my comment will read it, and the guys like you will just go about your day writing down 5 paragraphs for your docs and wondering why people can't use your crap.
Comments
If you take away how this looks, and start digging into the project from a beginner's perspective, this project is awful. I find this with most of the supposed "UI frameworks" out there for HTML. With a few exceptions, they mostly lack:
1. Good documentation that doesn't just define the framework, but teaches you how to use it and get stuff done with it. Code already defines what it is, your docs should tell me why it's this way and how to use it. In Kendo UI they've got a list of dependencies for javascript projects they need, then a few code snippets with no explanation as to why or how they work.
2. Good sample code, in a full complete project you can download, with documentation on getting it up and running. Your first sample code is how everyone will write code using your project. If you've got bad samples, poor formatting, and weird file layouts (or none), then that's what everyone will write and that's what you'll be known for.
3. Examples that gradually increase in complexity. Start off with a simple hello world, graduate to a chat app or something simple, and get them to a full blown large application. In this Kendo example they've got a demo picture viewer, with no explanation for how it was built, and viewing the source it looks like a huge mess.
4. Humor. These kinds of documentation are boring as hell, especially if you're just defining everything. It doesn't have to be insanely hilarious, but at least throw a few little funny tidbits in the code. Even the great tech books of our time have tiny little jokes for the people who pay attention.
5. Finally, these frameworks rarely have a "theme". MVC is a theme. Convention over configuration is a theme. There's only one way to do it. There's more than one way to do it. Themes work to help people keep the script for why everything works the way it does in their head.
It's too bad because this looks really good, and it could be the most awesome thing on the planet. But if I can't figure it out even if I want to, then I'm never going to try.
Finally, none of what I wrote above applies if your project is for fun and not meant to be a "product".
I agree with your points. Tutorial-style documentation is a way to go.
The main problem this framework has isn't its reference-style documentation (if a framework looks good enough I'm willing to do some extra work figuring out how to use it). Kendo's real problem is its licence. Apart from seeing how "awesome" it is you can't do shit with it.
Here's the licence: http://gd.is/qDdw
Read the FAQ, the beta version has a different license than the full release will:
Q: How is Kendo UI licensed? Is it open source?
Kendo UI is dual-licensed, Commercial and Open Source (GPLv3).
The Commercial license includes full source, professional support, access to the latest Kendo UI hotfix builds, and priority influence on the Kendo UI roadmap. During the Beta phase, the framework is licensed under a Beta license and no commercial license is available.
Thanks for that
snippet below:
1. Grant. Telerik hereby grants to you, and you accept, a non–exclusive, non–transferable license to install and use the Software for evaluation purposes only, solely as authorized below. ....
I must admit that I haven't checked your list against the Kendo UI. However +1 for a nice description of how to present a framework to potential new users.
Good lineup. However, I think that #4 is only appropriate in beginner's guides—docs always should have some boring reference section with quick navigation. HTML5 boilerplate lacks that. Jokes get old fast.
Perhaps some good examples should be mentioned… I think, SproutCore handles points 1-3 very well (http://guides.sproutcore.com/), but lacks #5 a bit. Django's documentation seems to have most of these, too. (These aren't HTML UI frameworks, however.)
Sproutcore fails on another point though with making too much "improvements" on version 2.x. Why would anyone consider using sproutcore 1.x if it's already deprecated, and version 2.x is far from ready, as well as the docs. The sproutcore demos doesn't even work. You gotta have working demoes. There's no excuse for that - try getting your boss to accept a framework with no working demoes.
If you don't manage to get a home run with version 1.x just stick with it and fix the damn bugs, instead of doing the big rewrite, with the promise that it'll eventually work. It'll just work if you stick with it and fix the last 10%.
[deleted]
How is it wrong? He's making good points. Do you have counter point to his exact statements?
Hm. If you look --> in the documentation <-- you find your first protest invalid. And in those docs you will find plenty of sample code, for your second protest, and examples (#3) to go with them (what is sample code if not an example?). #4 Protest too much? #5 Does a framework's theme need a template, too, or will a motif do?
I looked at the --> documentation <-- and when you have a single page of "yo download, it's awesome" and then a page like this:
http://www.kendoui.com/documentation/javascript-dependencies...
And other pages that are just enumerations of things that are in the code, then you've just defined it, you haven't told me how to use it or why it works the way it does.
Instead, they'd need docs that lead the user through step-by-step breakdowns of where things are, why they are there, how to exactly build an app from nothing, and get it working. They've got none of that. Just a .zip with some crap in it and nothing that says what to do.
Then, your idea of "sample code" is a couple of blocks of js on an HTML page? Right, I need HTML, Js, server setups, everything needed to get it working. If I don't have that then you've skipped over a ton of shared knowledge I don't have and that you need to take out of your brain and lay down so I can follow along.
"Protest too much?" You're a dick. Seriously, I love you guys who come in talking all tough like you're so damn right and really you just pedantically split hairs then throw out ad hominem attacks while claiming you abhor them.
But, then again, like I give a fuck what you think. The people who will actually benefit from my comment will read it, and the guys like you will just go about your day writing down 5 paragraphs for your docs and wondering why people can't use your crap.
you want free software with great documentation, and you want it to amuse you too. anyone can ask for that stuff, far fewer are prepared to help out
I don't think he 'wants' anything from the project. He's just offering the developer some advice on how to gain traction.