My first impression

Yii 1.1 Installation and Setup
1

Coming from a modest framework (CI) I must say that I like the Yii aproach but I find it very hard to put the pieces together in order to create a general idea about what goes where does what. The documentation refers too many objects and links too many pieces in one phrase which makes it almost scary for Yii beginners like me. I searched for a simple thing like how to add language strings or how to edit the default language and I landed here. If you look at the page you will notice about 50 links going to 50 pages but still, my answer is nowhere to be found or maybe I’m lost in so many page relations (it’s like the wikipedia). I think you have another comment in that page from another user like me.

@tixrus:

Unfortunately I don’t know what to point as an improvement but I can definitely say that the documentation is very complex, scary and very hard to digest. At least for people starting up with Yii. Please have a look at CI’s documentation and read their pages about each thing in part. There is no LINK to NO Api etc. Each page tells you everything you need to know about something from start to finish, very simple explanations to approach new users very smoothly. Very well sectioned into “how to load”, “how to edit settings”, “Usage Examples (VERY important - this is the part where our brain understands best)”, “where should be used” and nothing else. Everything advanced should probably referenced at the end of the tutorial.

I had to google and look at videos, study the provided demos just to find out what is a component, I still don’t know that for sure but I’m making an idea.

In the very second proposition the author skipped the whole idea of making a documentation and jumped to api explaining and injected a url already. In the third, guess what, we’re referencing another page from the api and explaining it. This is more like an API documentation rather than a user documentation.

Once I start to master Yii, your guides will probably make sense and prove to be quite helpful but I’m not going anywhere at this moment. I’m left with way too many unlinked pieces about this framework.

2

Strange you’re saying this. The framework definitely lacks video tutorials. But I was studying the framework from the guide. It’s quite good. You should only try the things that are explained there. Follow the blog tutorial, that’s a good start to understand how that works together.

In February-March 2010 we’ll have a book on Yii (I’m writing this together with Jeff), hope things will change then.

3

That’s the whole thing. It’s hard to start with what’s on the guide because everything in there distracts me to so many api pages. The blog tutorial video is more like a copy paste video which builds the application without explaining too much of the code being pasted there. I had to put pause very often just to be able to follow up with the narrator.

Right now, for newbies like me, a cheat sheet and explanation for each method in part would be a kick start but nothing more, I don’t want to know anything about the API yet. Just how to instantiate, how to use, where to use. That’s all.

I’m just writing this to give you a first impression, nothing wrong in it, I’m not mad nor frustrated, I decided to stick with Yii because it sounds promising and I want to be able to see what is capable of.

When I first started with frameworks about 3 years ago, I didn’t had a clue about what that is and what a mvc really means. But the documentation referenced above got me going within a day or so and I was excited. Every new application needs it’s “WOOW, it’s so simple” to attract new members.

The best thing to do when testing a documentation would be to ask a php beginner, with no clue about what a MVC is, to try and build something simple with your framework, maybe a login/register/forgot password combo. If he does that within a day, you’re on track, if he fails you need to tweak it until you answer all the programmers left questions.

I’m willing to help building a documentation suitable for everyone if you like, or at least propose a structure which covers my question marks at this stage.

Good examples (please moderate if I’m not allowed to do this here):

http://www.doctrine-project.org/documentation/manual/1_1/en/introduction

http://codeigniter.com/user_guide/

http://propel.phpdb.org/trac/wiki/Users/Documentation/1.3/UserGuide

4

When i firt read an article on Yii, i thought it was quite promising. I decided to give it a try. Coming from a framework that is distriuted with a skeleton app for quick startup, i found it rather difficult to start an app on Yii. I did a bit of searching on the internet on how to get started cuz the documentation on how to get started tells how to with CLI. Frustrated, i decided to search for another framework but could find none that i found as interesting as Yii. Eventually i decided to try Yii again, i found this post http://www.yiiframework.com/doc/cookbook/3/ which was really helpful to me. I then used the yiic tool to generate the test app and started experimenting from there. I asked questions in the forums whenever i’m not sure how to do something (or cant find out how in the documentation). I also started diving into the Yii core to see how stuff works and i found that was better for me. It’s a given that the documentation could be made clearer for beginners and could also incorporate more topics and some code examples (i think many people learn faster from code) but i also realize that the Yii core is relatively large and could take some time to document. For now i think we should just keep at it. Either way, things will get better in the future.

5

Thank you for your comments. Yes, we already realized there is a gap in the documentation that makes it difficult for new users to start using yii. The blog tutorial is perhaps too complex to start with, the definite guide focuses more on defining individual concepts and features, and the cookbook articles are mainly about individual development tasks. What we need is a series of articles describing every details that a new user might need to work with when starting a new Yii application.

6

Yes, something very simple, a sample application which covers the average user’s needs with more detailed explanation:

  • how to add language files and language strings and how do they get loaded to be globally accessible through the application

  • how to edit system configurations from within the application. Most of our projects will let the user edit settings from the comfort of their browser

  • how to access handy libraries (image manipulation, array helpers, request data (post,get etc) - if they exist

  • how to store sessions, flash data sessions etc.

  • where to place user created libraries, why in components, why in extensions

  • good practices vs bad practices ( highly important as it keeps us avoiding from the start things rather than fixing afterwards )

  • a FAQ page which covers the basics of the application, every little question mark

  • a lot of COMPLETE code snippets for each page of the documentation in part, don’t use partials as we can’t link them in our logic

Every framework has it’s challenge because you have to teach the users the framework’s language before they can get to something. That means teaching them as best as you can what was in your mind when creating x or y or z. They should be educated to think and look at the parts from the same angle as you, the developer. If you get this done good, I’m sure the popularity will rise as we’re educated to follow the same logic behind the application’s flow. I’m better at criticizing documentations rather than create a strong one but I hope this thread gets somewhere as I only wish the best out of Yii.

Look at doctrine’s docs, there are so many examples and code snippets that I can’t get wrong. I implemented Doctrine in less than a day without a problem. They do a very good job explaining what they had in mind when building each component.

It’s like that funny Top Gear show where everyone was so excited about the arrival of the new BMW M6 but it took them 3 hours just to start the radio because everything was operated from a very sophisticated joystick lol.

Good example of what we need at start: http://www.yiiframework.com/forum/index.php?/topic/4463-how-to-add-a-new-language-file-and-how-to-load-it/page__gopid__23733&#entry23733

7

I’m adding my little newbie vote to this being a priority. Documentation for volunteer driven projects frequently lags behind the development curve – at least in part because the people who best understand the system usually want to code new features, not write introductory documentation.

I just went through the blog tutorial, and I have some strong opinions. The tutorial as of 1.09 seems to start out as roughly two thirds clear introductory tutorial, drifting down to only one third introductory material along the way. (not trying to be precise about numbers here) The remaining fractions are descriptions of very specific points from the perspective of someone who already understands the overall organization of the framework. Personally, I could have used a lot more high-level description of how the larger parts of the framework are used together, a little more about design options at each stage, and a little less description of specific lines of code.

And this is a bit of a tangent, but I really don’t think it’s clear that users are supposed to read along with the blog demo as they go through the tutorial. Or at least I can’t find where it says one is supposed to do so.

It’s my opinion that good documentation converts people to a technology much more quickly then a few more advanced features. I’m really coming to like Yii, and I’d love it if the documentation caught up with the coolness of the code.

8

Ivo,

The fact is that you cannot write for all levels of developers at once. The learning curve of Yii is a bit high in the first hours, but then everything gets smooth in a short period of time.

This is mainly caused by specification-like tutorials and APIs, which is really good in the long run.

By the way, welcome to the forums!

9

pestaa is right, on the long run, the docs are getting very handy but, looking back, it was a pain in the ass to get started. My only concern now is to stick and learn whatever Yii has to offer as I always tend to create too much without knowing that many of the things I create are somewhere available. Good luck and welcome.

10

I have found the blog tutorial extremely helpful, but also extremely frustrating, since it has some fundamental errors that left me banging my head. I had to leave it three times out of sheer frustration. So, some very quick and simple corrections to it would make it far more useful to everybody.

The documentation for this project is very impressive, but certainly not designed for newbies. I agree however that it is the most important thing for long term users and should always have the highest priority.

Yii is incredible. With the YIIC tool, I can do in one hour what would take months to code from scratch. It really is a life saver for all the tedious tasks of putting together an application, leaving the fun and interesting stuff to finish and get my hands dirty.

I think a few more advanced tutorials would be very good for experienced coders to get a quick look at how things work together.

11

The symfony guys do a good job in documentation, which is a key in their success.

maybe someone should adopt the jobeet tutorial and "translate" it to Yii

http://www.symfony-project.org/jobeet/1_2/Doctrine/en/

on the other hand, the yii documentation is excellent for experienced developer

There are still some mytsics, but entering Yii is quite easy

12

I would like to add my 2 cents worth in agreement that the documentation needs to have a special “getting started” for us newbies. The existing documentation is excellent, if you know what you’re looking for. The problem is, us newbies don’t yet know what we don’t know.

I have a huge business application to build and I’ve evaluated more than a dozen frameworks, some very good, but have settled on Yii, because I can see it has the power and flexibility to do the job. However, getting started is an absolute bear for me. Trying to understand how things are glued together has resulted in digging through the code of the Yiic generated application to know where are the dependencies and relationships. It would be really nice (relieving) to have something for folks like me.

I just hope the idea of creating this type of documentation doesn’t get lost or forgotten. It’s probably not a priority for those who are already advanced users, I can imagine many newbies may never have the opportunity to become users, because they aren’t able to deal with the frustrations. I’m certain the Yii community would grow much faster, if it were easier to gain an understanding of it all.

13

maybe this will help you a little bit … http://www.yiiframework.com/forum/index.php?/topic/4722-link-collection-of-beginner-resources-pin-this-maybe/page__hl__pinned__fromsearch__1

–iM

14

Adding my 2 cents.

As of today I’ve spent about 40 hours struggling with the Yii learning curve. I’m a fairly experienced php developer and I have code sites from scratch, done lots of Drupal work and Joomla work. This is my first shot at a framework. I’ve just spent about 2 hours trying to find info on how to best include 3rd party javascript libraries… with no satisfactory answer.

Frankly what is holding me on to Yii is the PDO out of the box and the speed. If it was not for that I’d be off to CI or Kohana because of the support and docs.

My impression is that Yii is written by engineers, for engineers. If you are creating it for hard core engineers (you know, the kind thatswear that Vi is the only word processor you’ll ever need) then theexisting docs are fine.

I’m not an engineer (I’m a dabbler). I’d like to see Yii take off but I think, as it now stands, the docs will scare off many people like me.

Wishing you all the best!