you will find Prado has brief description, important keywords, live examples and related code on the other hand Yii has description only.
Sometimes description is not enough and learning new thing is more easier with live examples and code. I’ve seen there’s a Yii playground and useful resources but those are scattered and hard to find when needed.
If Yii developer can have a look in this way it will be very helpful for Yii users.
Finally, thank you Qiang for this superb framework.
I believe the documentation is pretty well structured at this moment, granted that first time it looks awkward, mainly because most of the YII users came here to learn having other frameworks as backgrounds and they are just used to that documentation type.
The things that lacks in the classes documentation, are mainly the direct examples of using those classes in real world, but i believe in time, we will have those examples, meanwhile, the forum is a good place to start looking when in question.
Yes I agree with jacmoe, there should be a Yii playgroud where users can demonstrate some extra (or advance) features. But with "THE DEFINITIVE GUIDE TO YII" there should be some basics demonstration / examples.
Don’t you think if this type of basic demonstration www.yiiframework.com/wiki/48/by-example-chtml would part of definitive guide, then helps a lot newbie like me. It saves lots of time to find out such material in wiki or forum.
I understand Yii has long way to go… this is why I post it as “feature request” section. We hope, our wish will come true in the next version
I acknowledge that the first time, it’s hard to find your way around the class reference (API doc), but once you’ve got it, there is no need for more examples, the doc speaks for itself. The entire Yii framework is very well documented.
So, I’d rather suggest some kind of minimal “crash course” to understand the class ref. docs and continue from there rather than throw yourself in the painstaking job of maintenaing by-examples documentation.
i.e.: To pass an option to a validator, you’ll find in the docs […], you simply happend a key/value pair to[…].
This way you wouln’d need by-example and for more specific situations, the wiki is there
I second this. At the very least it would be great if it linked to relevant examples in the Definitive guide. - which I would have thought would be easy to put into the documentation via @link tags.
I find the structure and documentation very good. The class docs don’t need to be made fussy with example code, we learn by doing and once we’re up and running the API docs are more than enough. The Definitive Guide is the place for real world examples and hand holding and it does a very good job at that.
No offense, but not having an example to look at will make you waste time searching for it, and secondly, there are allot of newbies that won’t really understand what they do and will write vulnerable code, or they won’t write it at all(which is better than the alternative:D ) .
When i say i want to see examples, i am talking about things like the “Event/Behaviour” provided by Yii, these two features are amazing, but not only the documentation for them isn’t clear enough, it seems like searching google for clear examples will take you nowhere, so there comes the question, why bother developing amazing features if we are not able to understand how to use them ?
I have to agree. Although I really like yii’s documentation (guide and API are among the best I know), I remember missing the examples from the Prado documentation when I switched. Also, I needed some time to understand yii’s implementation and usage of behaviors and events.
Examples simply help getting you started. It is good to provide tools like the wiki where the community can help adding snippets and collecting best practices. But it isn’t the same as having samples included at the places where they belong and written by the people that implemented the framework.
Maybe provide them hidden/ folded by default, so one can extend code listings only when needed.
As a new user, I agree there are some improvements to be made like the ones already suggested. I am used to the Codeigniter docs (check out their User Guide), which are quite effective, organized, and nice to look at visually.
Everything is in the User Guide and explained clearly, with examples. You can get by with just the user guide.
From a front-end design perspective, I think the Definitive Guide should be put on the main documentation menu as ‘Guide’, rather than being a text link under tutorials. It doesn’t have the prominence I think it should have; New users should be directed there, and there should be content on the guide landing page. As a new user it felt like there wasn’t a central location. I experienced some other barriers to entry at the beginning that I’ll be trying to help improve in the docs.
I haven’t used the docs enough to know this for sure, but perhaps some wiki articles on common subjects could be moved into the guide, like hasanavi was suggesting.
I’m sure I will get used to using the API reference like UltraPhil says. I don’t think docs have to be so they take a lot of getting used to…but maybe I’m just too spoiled by Codeigniter
Cool, I see those. I mean on the sub-menu in the content area (square grey box that says ‘Documentation’) and the main dropdown, as well as a stronger call-to-action on the landing pages. On the site structure, I see it moving up to be a main menu item. Not a huge thing, but I think it would help.
Agree. it’s whole of a week that I’m trying to get thing working but when I look at documentation… “this is for doing something, ok? so here we go… Methods: one, two, blah, blah… - Properties: one, two,…” and thats it. yeah in many topics I can yet find good description and even examples but yet I feel lost in Yii::*.
Short story: New users NEED some examples, I mean "to use this thing do something like this: SHORT->CODE".
btw., if you think an example should be in the particular guide section and you’ve got it at the forum or elsewhere you can help Yii team by contributing it: http://www.yiiframework.com/contribute/
fortunately there is "larryullman[dot]com" to simplify Yii concepts for newbies.
thank you Yii team very amazing work you’ve done (you know ). I will give it more time to see if I can “start” my Yii::learn(); motor or no… anyway Yii or nothing else, I promise
). I will give it more time to see if I can “start” my Yii::learn(); motor or no… anyway Yii or nothing else, I promise