Documentation

Hi

I am not sure the documentation is receiving as much attention as it should. From past experience on other similar projects, the documentation is usually the weaker link. And it puts potential developers off.

I believe we should have a documentation that is of the same quality and standard as Yii itself. We need the one documentation that systematically covers everything.

In my view, it is not good enough to have a class documentation here, a cookbook there, a couple of tuts over there, and so on. A project like Yii should be systematically documented beyond the automatic generation of docs embedded in the code and have its own documentation team proportional to the size and scope of the project.

This is not a flame, I am posting this to generate a constructive discussion.

Cheers,

JG Estiot

Hi JG Estiot and welcome to Yii community!

A real developer is never put out by lack of documentaion. S/he always finds his/her way to achieve smth. The documentation is progressing no matter how fast. I’ve had my hard times understanding different things about Yii but looking at the code always helps…not to mention the forum where there are lots of experienced mates and are helping out lots of people.

The documentation you are talking about sounds somewhat utopian. Don’t get me wrong we all would love to have a full systematic documentation describing every dot and character but we also have to understand that master qiang and the team also have to go to work to pay the bills so I think they are doing pretty well with their timing. I can now see lots of bloggers writing tutorials on their own blogs regarding Yii, which is very good as they help spread the word about Yii.

My suggestion to you is don’t get discouraged. Yii is worth every second spent to understand it and you will appreaciate it when you start building large applications.

That’s my opinion…hope it helps

Regards,

bettor

ps and don’t forget to use the forum there will always be someone to help…

I think Yii still under heavy development and documentation usually lacks during this initial phase. Hopefully, we can start to see some books written about it. I think the community still too small and the number of "advanced members" even smaller, but probably big enough that they could start "cooking some books". :slight_smile:

Also, examples like "blog" is nice, but probably too big for a "new member" to start playing with it. Smaller examples are better.

Examples like:

a) A simple application with a Grid. This would shows just a plain usage of the view grid, data of the model should probably be hard-coded, or simply enough for someone to get the example running in minutes.

a) User Management, a simple application with user management. I think the extension "yii-user" is a great step on this direction.

c) DB examples: this area is very vast and many examples would be required. Starting with basic AR stuff. Next, show some tables relationships, and finally dealing XML and/or hierarchical data, on this step by step how to set up "Data Providers".

this is just some ideas. I have been "lurking" here since Dec 09, and the progress is tremendous.

In another thread someone had idea to allow comments under the API reference (like at php.net). I think it’s a good idea.

Well as you may know a new Yii website is coming sooner or later and I hope we will have more possibilities for tutorials then (instead of cookbook only). qiang said in another thread he’s pretty busy at this time so I guess new website will still take a few weeks/months.

I have another idea, maybe something like cookbook requests? So one can submit a request and other people can vote for it (if they need it as well). This way the most needed thing will get done first (hopefully).

Hi,

ok, maybe the documentation is not perfect (nothing is) but when I began with Yii, the definitive guide, was enough…it was of great help. It may take a while to read it all, but it is full of examples, and from my point of view contains what is needed to quickly start with Yii. That’s the main reason why I’m now using Yii … I followed the documentation and could quickly build my first web app !! cool !

Moreover there are examples provided with the release (in de demo folder), intresting stuff in the cookbook, and good discussion on the forum.

That is only my opinion guys :)

8)

Hi Estiot,

uhm, you do know the Guide, don’t you? Just wondered, because you didn’t mention it and it already covers most Yii principles very systematically. I admit that you might have to read it a second (or even a third) time, as the information in it is really condensed. But there’s even a international team that keeps all the different translated versions of the guide up to date. So we already try our best to make things easy (talking as german translator here…).

But you’re always welcome to help improving the guide. ;)

It sounds like people want a book that guides them through Yii step by step.

Someone is writing a book about Yii (it’s on the forum somewhere).

The documentation as is should be sufficient for most developers. Once the book comes out I think it just needs to be promoted on this site. The book should then decrease the learning time.

Forum + API is the best documentation for me now ;)

i’m agree with Mike: Yii guide is very complete, but it is very condensed too. You have to read it two or three times.

With forum and API you can start a project very quickly.

A comment I made on a different thread:

There is a lack of expert support available for newbie developers. It often takes days for queries to be answered in the forum. I think in the API reference there ought to be example code/solutions for the most useful methods.

@GSTAR:

Don’t get me wrong, but what is your suggestion what we should do about that? ;)

Remember, all of this is volunteers work, even giving support in in forums. A lot of people already give support - and often answer the same questions again and again. So from a new user i’d also expect to use the forum search before complaining about missing support.

Sorry I was just commenting in comparison to other framework/CMS forums I have used. This forum has by far the slowest response rate. I understand it’s a new framework and that it’s all voluntary work, but the lack of timely support, along with lack of example code solutions means newbie developers like myself spend weeks rather than days on small projects.

Sorry for the rant but it just gets frustrating for me sometimes. I don’t mean to offend anybody, Yii is still by far the best framework I have used :)

it’s up to qiang and the team but I think hiring a few more coders to the team to write down examples of various code might be a good approach…

As someone who has struggled with the learning curve, I would certainly appreciate clear, simple explicit example code for "typical" application activities - ideally broken down into "this goes in the model, this goes in the controller, this goes in the view" so that us MVC newbies can get schooled…

OTOH, I have gotten a lot of help in the forum. I would venture that response time to questions will NEVER be as fast as the questioner would like, because when we post, we want the answer NOW!

That said I am feeling very good about Yii and excited to use it more and more.

My thoughts are that:

The documentation is very good (in most areas), but lacks regarding examples, which is key. The biggest issue I’ve seen is lack of examples for classes that expect their configuration parameters as an array, as it’s not immediately obvious the structure that the array should reflect, what keys/values are allowed, etc.

I’ve spent plenty of time researching alot of the array configurations, as often there is nothing mentioned in the forums, and other IRC users are typically new or haven’t used the class being referenced so they don’t know either.

Additionally, I believe the documentation navigation isn’t ideally structured, so alot of areas that should be promoted more highly, aren’t.

And the search functionality is hit-or-miss, so checking existing sources isn’t always reliable.

I think the main problem we’re encountering is that this is such a young project. Once it starts to mature, we’ll see excellent documentation, support, and growth.

I agree that Yii is the best framework I’ve worked with yet, I’m just frustrated that it doesn’t have a 6-yr old community built around it already ;) :D