Basically just have ONE example at the top of each class reference page, that shows the most common usage of the class. That will probably save a lot of repeat questions.
Some class reference pages already have some examples, which is helpful but for instance if you look at the CDbCriteria class reference page there is no example usage.
@Mike and @GSTAR
I agree
Yes and no… as we discuss the API section of this site. Yii playground is a great place to look ‘outside’ of the Yii site, and that for newbies who review the API still a bit cumbersome to go back and forward from the API to other sites. Don’t you think?
Agree with samdark. For examples code in Yii, I think we can focus them on Yii Playground instead. Although currently it is not too much examples, but I think it helps enough already though. When the first time using Yii, Yii Playground’s example help me very much…
@Antonio
I don’t think this is a deal at all. Nowadays browsera are having multi-tab functionality. We can open one tab to read API while the other view the example codes in Yii Playground. No necessity to back and forward the page then…
Well, not all work can be done by developers, and example can be done by community.
Each of us has the possiblity to leave comments, why not to leave lot of comments with lot of examples? Let’s write more comments, Yii community, and we will have a more detailed documentation.
The time of developer is gold, why we are suggesting to spoil it in write example in documentation when each of us can do it? Better if developer will fix bugs and develop new feature while community wirtes wikies and examples.
Good idea zac
I find Yii documentation too advanced for beginners, but it’s an exaggeration to call it poor.
I am looking forward to more examples!
I find the documentation of jQuery very user-friendly, wherein methods are clickable and will transfer the user to examples and demonstration. Is this possible with Yii? It would be a great help for beginners and advanced users too!
Well, the first and obvious thing to do, is to point user to the method/property details, not to the table of contents (if I may call it that way) of the component in question. Most times you just open the link in a new tab, but you are forced to make one more click to get to it’s details.
Also the search should not point you to the table of contents, but to details if you are looking for the property/method of the class.
Here is an example:
We enter in to the API search “CGridView.columns”. Now it will point you to http://www.yiiframework.com/doc/api/1.1/CGridView#columns . Better to point straight to http://www.yiiframework.com/doc/api/1.1/CGridView#columns-detail , because short description mostly is, well, short 
Methods, whose description consists only of that short description usually are self-explanatory and autocomplete in IDE gives all the description you need (no need to go to the API docs).
As for the comments to the API docs, well. It makes sense if Yii had docs like PHP has - a page per function/class/method. As it is right now, comments are just far far away in the bottom. You just usually don’t scroll that much down and that way the comments and their value is lost. To make comments work, IMHO, the docs should be changed to a php.net style layout, so that every method/class/function has it’s own page, witch can be modified and extended with good examples.
Also, maybe linking recipes to the classes would help with the examples.
One big caveat is that writing good examples is just damn hard. You need some good idea on witch to base the examples and work it with some advanced usage. Maybe it can be some kind of administrative panel with advanced grids and CActiveForm components linked together and so on for the CGridView and Co. But that’s just part of the docs. Probably different parts need different examples to illustrate the power of Yii.
It’s difficult to decide what is best… to get to the method/property table or to the details…
Problem is if the method/property is inherited…
For example if you enter CGridVIew.dataProvider you would go to the CBaseListView.dataProvider as this is defined there and just inherited from CGridView…
When you go to the table… you can see there that this property is inherited…
So need to think more in providing related examples, more and more. It would be easy for beginners and catch soon than any other frameworks.
Well, that really depends on how the internals of the docs work. Probably information that this property is inherited from some class is available and you can decide if to point to #*-details or to list of properties/methods.
I believe API docs code isn’t in the framework source? Maybe I can get an access to the code? I’d take a look if it’s possible and make a patch
The only problem i see with user contributed stuff: It’s missing review to assure some quality standard. Therefore i’d rather advocate for a team, that maintains a dedicated example section. Maybe with 1 page for each class, having some “official” real life examples on top and also allow user contributed examples in the comments. The team should also stay in contact with the dev team which could quickly review new examples to ensure high quality and sort out issues.
The code is on SVN in the folder BUILD - http://code.google.c…2Ftrunk%2Fbuild (ApiCommand)
But the problem is to be consistent… it would be even more strange if some properties would link to the -detail and other to the table…
Hello I am a newbie and I also agree with the topic.
Yii Framework is really good but its doc is very complicated to understand
I’ve been searching for the explanation of using Yii::app()->lc->toLocale(…) as I am trying to make it works as basic date and time
,but still I haven’t found any though it said it is not a part of Yii. I already have the LocaleManager Component and i18n folder and its en_us.php
This is a confusing example for me and that I tried so many time and I still can not figure out where and how I can create a ‘LocaleManager’ object name lc for example.
Dude, that’s got nothing to do with Yii documentation!
Read the official docs first:
doc/guide/1.1/en/basics.application#application-component
Then read the community-contributed page again…
To be fair, Yii’s documentation is one of the better ones. The guide contains all the examples you need to get started. The API docs contain all the info you need to dig deeper. The community support from Yii enthusiasts is also great and you will rarely not get a response.
I think beginners to Yii are often beginners to PHP and/or MVC/OOP in general, and this can lead to confusion for the users as they think the issue is in the docs or a part if its code. My advice is to stop and think when you have an issue, look through the Guide for examples, then if still not clear, search the API and forums, then if all else fails, post the topic of interest, but before you do, read your question back to yourself before you hit post and if it doesn’t make sense to you, I won’t make sense to us answering it.
I agree that the documentation is decent (and better than most). Improving it, IMHO, means identifying the target audience. Who is Yii for? If Yii is for all levels of developers, then it makes sense to spend time creating a section specifically for programmers without a lot of PHP, MVC, or OOP experience. That means thinking like a beginner. If we state that Yii requires intermediate skill and MVC/OOP experience going in, then we should spend our limited resources improving other areas while being upfront about the skills required coming in.
Too many people forget that there is a learning curve. The newer the concept, the longer it takes to grasp it. That doesn’t mean you automatically bar newcomers, but people aren’t always realistic, especially on open source projects. We all try to fly before we can walk.
Just thinking out loud here, but it would be cool if we had a beginner’s, self-paced tutorial (like the blog, but with other concepts thrown in) and a proficiency test that tagged successful test takers with a star in their profile. If we encourage newcomers to go through the process, they will at least have the basic knowledge to build upon. It might even shorten the learning curve.
Are you kidding? Have you ever worked with any advanced framework or tool?
Yii is one of the best documented PHP frameworks. If you have knowledge about programming, design patterns, OOP you will face no problem using it.
I agree, with Pedro84 - you will need some basics about OOP. Reading goes fast, but understanding everything takes its time. With the Yii Framework are many possibilities to do things efficient. But the first two months were a little bit confusing. But until now I didn’t need to do a single post in the forum. I found everything I needed.
My resources were:
PHP Documentation about OOP
Forum
Definitive Guide to Yii
Wiki
Class Reference
Stack Overflow
Playgrounds
Other websites
Blog tutorial (which I hated because of this blog application - personally I wouldn’t code a blog application - but it’s helpful for learning I guess 
)
Yii Book Yii 1.1 Agile Development - Yii Framework Forum (but didn’t find much useful information there)
and last but not least I used the live-chat for 2-3 times when I had already a certain knowledge (e.g. knew what I was doing…)
One of the wiki articles which helped me most
http://www.yiiframework.com/wiki/181/relations-belongs_to-versus-has_one/
07.07.2011
I know it’s been 10 years, but seriously, one of my first task with Yii is to create migration script. Yet a simple line such as
'role' => $this->tinyInteger()->notNull()->defaultValue(0)->comment("0 - user\n1 - moderator\n2 - administrator"),
take such a long time to find, some of the options belong to SchemaBuilder, some belong to SchemaBuilderTrait, some in ColumnSchemaBuilder, some in Command, etc.
I mean, I just want to know the list of the available option when I create a column, but it was so scattered. When I first used Yii, I used addUnique() because I didnt know ->unique() exist. Or I used addCommentOnColumn() because I didnt know ->comment() exist
I know when I put it like that it doesnt seem like a serious problem. However, I encountered many forums where people ask for something Yii support natively but get answered with some kind of “workaround”, with a lot of people follow along, because the actual document of that function is buried deep somewhere. Which may introduce unwanted side effect, or some kind of loop hole, insecurities, etc. which would decrease productivity, quality and also render the hard work of Yii’s developer useless. Which as a fellow developer I also dont want to happen