i was searching information about the Yii framework but its documentation es very poor, maybe this change soon…XD
i was searching information about the Yii framework but its documentation es very poor, maybe this change soon…XD
elaprendiz
What exactly do you miss? We are trying to improve it but we need feedback.
I think the documentation is very good actually. The one thing I would ask for is example implementations on each class page.
If you think that Yii documentation is poor you don’t know what is joomla, for example.
The class reference is very complete and clear, rely on it for any question.
I also think that Yii class reference is very complete and clear.
Maybe more examples is needed for beginner…
that’s the point. Im new to Frameworks and there could be more examples.
I would also appreciate more documentation about the connection to Databases especially how to handle
complex DB structures. More examples could help here.
Mostly i miss literature (books) from 3rd Partys you know there is just one yii book. That would help
beginners the most i think.
But for profesionnels the documentation is probably good and complete, but it leaks for examples especially for
beginners.
Yes: beginners (like me) needs more examples.
(Wow! I’ve written hundred posts!)
The documentation actually isn’t all that bad at all. The class reference is certainly excellent and there is sufficient info in the guide and wiki to get started pretty comfortably. There are of course certain areas that aren’t covered anywhere but for many of those you can find answers in the forums (or ask questions in the forums) or use the force and read the source. I think with Yii the community is sufficiently large now so lack of information on how to do something shouldn’t be an issue.
Coming from codeigniter it would be good to have an equivalent user guide.
Matt2012
That’s hardly possible since CI is much more lightweight solution: no AR, no cache drivers etc.
The key thing is that the structure, layout, examples and general easy to read documentation
with codeigniter is why it is/was successfull.
If you look at the CI documentation every line of
text is followed by an example of the code. This really improves a beginners undertanding as
they can easily relate the concept to how it can be used.
All the main topics one needs to create a application or clearly setout in the index page and
allows you to quickly find an aspect of CI you might need to reference.
Also I would disagree with the view that CI does not have AR and Caching as clearly it does.
http://codeigniter.com/user_guide/database/active_record.html
[url="http://codeigniter.com/user_guide/general/caching.html"]
http://codeigniter.com/user_guide/general/caching.html[/url]
Now that I knowledge of Yii and have created one app with it I find that it’s
a lot easier and cleaner than CI, but It took me a lot more effort to
learn and persevere with, Also I had all the experience in CI which also helped and a I think
total newbie in frameworks would probably have given up earlier and found something easier to use.
One thing that i’m missing in API reference is that some options just don’t have examples.
True, mostly they just link to the description of similar property in some base class, but in that case it looses specifics of the compoent in question and makes you traverse through a bunch of pages. It looks like this:
Doing it 20-30 times a day is just waste of time and really disturbs the work. Now I know the basics and rearly having that “happy click” path, but still when I start using a component new to me - that’s the case.
But examples should really help with that. I was wondering very long time that htmlOptions params are accepting and in what maner. Sure it’s now obvious, but at the begining I didn’t found any explanation of what it is and what it does.
I have to agree partially to the “link problem” in the API docs. E.g. today i tried to figure out, how to use <optgroup> with dropdownlists. I had to go through a chain of 3 links in the docs before i finally got to “CHtml::listData” - and ended up reading the source code, because the information i searched for wasn’t there (or i missed it).
Situations like these are rare - but still they occur. What can we do to improve this situation?
I don’t believe at all that its documentation is poor but it is true that some bits and pieces are missing like the ‘examples’ per API class method but at the same time, this is why the comments under every page in the API section exists.
Reading the source code is what I do when I wonder the internal functionality of a function or procedure, tracking back every class, to fully understand and then apply my solution to the problem. I know this could be tedious but at the same time, I think is a good way to learn the framework after you followed its tutorials.
Nevertheless, best API object practices could be a rocking improvement (for newbies) into the API, describing ‘by example’ how to use its functionality on a ‘per-method’ basis.
About what Mike last said, I proposed a section in the form for ‘function hints’, too small for a wiki functions that could help others implement what they are looking for (ie using <optgroup> with CHtml::listData).
silewi
I came to Yii after some years with CI so I’m pretty familiar (and impressed) with CI docs.
CI have drivers for caching only in Reactor version that doesn’t yet have releases. In released versions only file cache is implemented. As for AR… well, CI’s AR equals Yii’s query builder. So it’s not really AR.
Yii codebase is larger, that’s why if we’ll fill documentation with all possible examples like in CI docs, it will be too bloated. Right now you can find a lot of useful things in API descriptions linked from the guide. If you miss examples in some places very much, please tell us and we’ll check if we can add them.
Psih
Report these as issues please. We can’t describe each and every method usage but, I think, per class examples are OK.
Psih, Mike
Any solution to click-click problem other than adding examples everywhere?
Hmm, having examples everywhere blows up the docs. I like Antonios idea and think some sort of "demo section" would really be very helpful.
Maybe we can have dedicated pages for the “heavy” parts. For example we could have one page dedicated solely to “dropDownList” and all it’s related issues. Showing examples for each and every option: how to create a dropdownlist with a simple array, how to use CHtml::listData, how to get optgroups etc. Same for radioButtonList, etc.
Just brainstorming here …
Don’t you think that is part of Wiki?
I know, we have some wiki pages about this - but i guess i wouldn’t search for them there as a newbie. The suggested demo section could be part of the official docs.
You can’t really compare it, but in PRADO we had dedicated pages for all controls and links to extensive demos that showed all the bells and whistles:
http://www.pradosoft…e=Controls.List
Yii is different, as e.g. a dropdownlist isn’t a component anymore. But still dedicated pages showing the code + html output could be useful for a lot of methods and even some classes.
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.