Hi, I have been studied and I would like to suggest an way to improve the framework’s documentation.
It would be like so:
It can be found in .NET Framework more specifically in the MSDN documentation (you can download and install on your computer).
What do we have there?
It is similar to Yii chm documentation, but it has an example of use for each class or component found in the MSDN documentation.
What can we have?
below each class description, like in MSDN documentation, we would have a fragment code that would give us an example for the current class.
it would avoid many questions and doubts about the current class or its attributes and would be easy to improve, because anyone would be able to send a real code snippets to be published.
take a look at the page
it shows the System.IO.File class
you can see that can be found more than the class´ description.
there are examples that demonstrate some of the main members of the File class.
I see many members that also complains about the few examples in the documentation. Especially the foreign ones.
Qiang, what about a project for the development of better examples in documentation? Maybe a we can ask for contributions from the more experienced users and form a documentation team. I would like to participate
Another interesting feature that can be very helpful is the API reference translation. Any plans about that?
Thanks for your suggestions. I think in the long run, we would rely on Yii users to help improve documentation. The Yii cookbook is such an attempt. We are currently revamping our website. We plan to enhance it to allow more user participation.
(I know it’s considered politically incorrect in some Occidental nations to criticize non-native speakers (and writers), but I mean nothing personal. I am, after all, a non-native speaker in the land in which I live.)
qiang, how do we go about improving the documentation when, to all intents and purposes, it is closed?
It’s great that there are docs, but they are written in the wrong voice and thus very confusing to native speakers. Technical writing is terse and precise; it has to be. And it’s not easy.
I’ve also learned, from experience, that folk like a lot of examples – usually of increasing complexity – to go with more formal definitions. The current docs are very light on these. I’m sure more examples would be a big help.
I share oalexandrino view and use the code now – stepping through if necessary – but I think that’s a poor way for folk to learn, in general.
The cookbook is a good start, but it must be managed. Someone has to "own" it. The same will be the case with a wiki. Open forums can be great resources, but they can also degrade into useless pits of noise.
Documentation is a big part (more than 50% IMO) of a framework. I think forming a documentation team is a good idea. The only problem I am not sure about is: will there be any native speakers who are good at writing and are willing to write Yii documentation? If we are lucky enough to have one or two such persons, I think we would be able to improve significantly the overall quality of those closed documentation (the guide, API docs, etc.). Anyway, we will try to recruit some new team members in the near future.
For open documentation, I agree with you that the cookbook needs to be owned and better organized and managed. We hope the new website can reach this goal.
YII core is very well documented and that is why I chose it over other PHP frameworks.
One way to retain the core documentation as closed is to use similar to the class model for the documentation, so the core documentation is closed to modification (except by the YII team) but open to extension by users. For instance user might add examples.
Indeed there are but that is not very structured. They don’t belong to a particular method but to the whole class.
We end up with comments about a variety of methods displayed in order of posting time and only connected to the method by being on the same page but way way down the bottom.
It would be nice to somehow associate code examples with the methods they refer to.
