tutorials, books and guides

[tkoomzaaskz]

Dear Community,

I want to share my opinion about a big number of books, tutorials and other kind of guides released during last year.

I started to use Symfony more than two years ago, the thing I liked the most about it was that there was just one 'definitive guide to symfony', where all basic, advanced and really complicated topics were covered. And now, since new versions are going to be released, since the framework is changing its default ORM, there's a big mess growing around...

There are separate documentations for everything (I'm talking only about the last current stable release):
* definitive guide to symfony 1.2 using propel (no doctrine version)
* guide for using forms
* guide to using symfony 1.2 (kinda what's new)
* cookbook for 1.2
* symfony + doctrine book
* symfony + doctrine cookbook (which is different)
and so on, and so on (I've just finished making order in my list of links)...

Well, imho, it's all separated way too much one from another... I know sf 1.2 changed MANY things, but it doesn't mean that searching for information should be more difficult because of it. I'm very happy that there are so many tutorials, but couldn't it all be stuck together a little bit more? I'm looking forward to what the docs for 1.3, 1.4 are going to look like.

What are your opinions?

[nedy]

I definitely agree with you!

I've also started with symfony about two years ago by using the "The definitive guide" - it was very easy and real fun for me as a total beginner to the symfony framework (and php world) to grasp the framework's fundamentals and dipper things as well.

Now I am using symfony 1.4 for my projects, but I really miss the simplicity and clarity of the "The definitive guide to symfony book". When needed I still consult the documentation for symfony 1.2, but I think that is not the preferred way for the end-users.

I belive that "The definitive guide to symfony" should be somehow "ported" to the 1.3 & 1.4 version of symfony as well. (I don't mind if there are separate tutorials/guides e.g. for Form framework, Doctrine usage etc.).

[halfer]

I'd tend to agree as well - the Definitive Guide was great, but the primary guide now appears to be a tutorial, which is great for learning, but not so great if you want to dip in for a specific how-to-do-x.

[tkoomzaaskz]

Working with sf 1.4 is even more difficult than with 1.2 (I mean it's less comfortable). The main source of knowledge about sf seems to be Jobeet.

My solution is to write ONE documentation for 1.3/1.4 which would have more chapters (definitive guide book + forms book). Besides, it should have static links to doctrine documentation when needed. Imho such links between documentation would be useful.

Unfortunately, I found some class files in sf 1.4 which have blank documentation blocks ~ ~ .

The symfony project is getting bigger and bigger...

[DBA_Alex]

I started using symfony with 1.1, when documentation on all the changes was very sparse. The documentation has improved greatly since then. The three core books for 1.3/1.4 are nice references, but it can be very frustrating trying to find specific examples for a particular function/best practice. I would also agree that another 'definitive guide' would help that along with an improved community wiki.

[skyblaze]

I also think that a "Defenitive guide" updated for the 1.4 version is a must!!

[malas]

+1

since version 1.1 and the new form system symfony is no longer the best documented PHP framework ~ ~

for future releases documentation should be a must.

[halfer]

+1

since version 1.1 and the new form system symfony is no longer the best documented PHP framework ~ ~

for future releases documentation should be a must.

= Sigh =. We get quite a bit of this kind of emotive blackmail here, in the form of "symfony is no longer the best X, but if everyone jumps to it, I may be generous enough to change my mind".

@malas: a far more constructive approach, if you're interested, would be to state exactly what you mean. How on earth is someone meant to use your input practically if you don't even specify which PHP framework is better documented?

In any case, new posters on this topic are invited to read another thread in which Fabien responds. And, everyone, please keep it civil, positive and friendly. We've had enough immature and abusive posts about the documentation to last us for the remainder of the year at least!

[malas]

any framework which has its stable release documented.
http://framework.zend.com/manual/1.10/en/
1.10 is not even stable and they have documentation on it.

to be more constructive

i think there is no real reason to rush for v2.0 if the v1.4 is not even fully released yet.

i mean how the new users should feel when opening the book section of documentation an see "The Definitive Guide to symfony" is not yet available in English for the symfony 1.4.
and it's almost 2 months after the release of it.
it would be nice for Sensio to declare a week of Documenting and instead of coding for the new 2.0 release give more people writing the documentation tasks

now about the form framework
the situation here is even worse, because it was introduced in sf v1.1 and the form book is not finished.

when i started using symfony back in the v1.0 times, when i had some problems understanding any part of the framework i could check out the book, now i am using v1.2 and must search the API constantly.

i know i wrote a lot of stuff, but lets be sincere, the condition of documentation after the release of v1.1 is getting worse.

halfer, i know you want to kick my ass, but stay cool ~ ~
it's just my opinion ~ ~

[halfer]

@malas: by re-stating the same views again, from this thread and from the other one, you demonstrate that you have missed the point I am making. Let me state this very clearly again. I am not disputing the docs cannot be improved upon. I am sure they can. In this thread, however, and even more so in the other one, I am trying to improve people's method of feedback. I hope we can all agree that this is a good aim?

All people need to do is to make their criticism carefully. It is a shame I have to labour the point, but it seems to require spelling out for some people. There is no "must" with the documentation. It would be +great+ perhaps, or +very useful+, but if I said you personally +must+ write some documentation for me, you'd wonder why I was ordering you to work for free, wouldn't you? If I told you the standard of your coding was "even worse" or "getting worse", especially without praising anything else, you might also feel a little aggrieved. Right?

You assume wrongly that I want to "kick anyone's ass" - you just need a little guidance in how to provide constructive, polite criticism. Addendum: I am honestly not trying to pick a fight - just trying to get everyone to play together nicely ~ ~ .

Anyway, for folks on this thread and the other one, I should be thrilled if, as well as being more positive about the software and docs that people already have downloaded free of charge, people could start raising tickets and creating patches for the docs. Now that really would be a great way to improve things! ~ ~

[tkoomzaaskz]

Guys, please calm down ~ ~

I hope the fact that we're discussing the documentation lacks here is already a signal for the sf core team that even the old symfony users miss some things in the docs and, hopefully, they'll remember it before releasing new versions.

PERHAPS, finishing forms book or copy/paste/update symfony 1.4 definitive guide would be VERY USEFUL (just kidding, halfer ~ ~ ) for the community in general, in comparison to the last Christmas advent callendar (which is more like a very good value blog imho), but nevermind.

I see an extremely good thing in the symfony community - lots of plugins created by the users. The entire plugin system is said to be rewritten from scratch to make it so useful as it is now. I'm not sure whether this would be a good idea, but maybe there should be some kind of a community documentation creating system? I'm sure that there'd be many cheerful people that'd be glad to help. But the question is the quality of such docs. I realize that symfony is getting bigger and bigger (less time for the sf core team), there are symfony live meetings in French organized (even less time for the core team), but, anyway, we can try to help. Symfony is free software, anyway!

Do you think the idea of community documentation has any chance of success??

[malas]

i understand your point. symfony is free, but more attention should be concentrated on the documentation in the future releases.

i never said that someone *must* do the documentation, i said that core team *must* react somehow and make decisions having in mind the documentation quality.

now we have some kind of community documentation via blogs, code snippets etc. however it is difficult to find it compared to the definitive guide in v1.0

i really hope that there will be some easy tool to edit the documentation because as we can see now, the core team just can not maintain the documentation and continue coding new releases.

the main thing is that we can not ignore the documentation problems ~ ~


P.S.
if you think my posts are rude - don't. it is just the way people communicate in eastern Europe - we say everything as it is ~ ~ pretty straightforward way, but it works very well here ~ ~

[tkoomzaaskz]

P.S.
if you think my posts are rude - don't. it is just the way people communicate in eastern Europe - we say everything as it is ~ ~ pretty straightforward way, but it works very well here ~ ~

On one hand it's true that we're damn straightforward, but on the other hand, this forum is not Eastern-Europe symfony users forum and PERHAPS it's a GREAT IDEA to respect other cultures and their habits (and don't force the others to feel like they were in Eastern Europe). Some people might get offended (like in the other thread - when someone wrote that docs "suck" ...

I wish there'd be a discussion about a community documentation system. Shall we (or shall I) mail Fabien and ask him about such thing? How do you all think?

[malas]

From my point of view, i was not rude ~ ~
and if the western europeans want to be democratic they should respect and understand other cultures ~ ~ this is a neverending philosophical discussion ~ ~

i think it would be great to mail the core team about some kind of community documentation tool ~ ~

[halfer]

OK, I appreciate the exchange - thanks to you both. I am sure no-one is intending to be rude, I am just saying that not everyone will see it that way. Politeness is the oil in the engine of collaboration ~ ~

In terms of community-written documentation, I think it is community-based already. You just need svn and either commit permissions or trac and a patch creation tool. However I would imagine you have in mind a web-based solution. Do either of you - or anyone else - know if such a thing exists already?

In terms if the Definitive Guide, you may not have seen Fabien's post on this - he has agreed to work on it for 1.3-1.4.

[tkoomzaaskz]

In terms if the Definitive Guide, you may not have seen Fabien's post on this - he has agreed to work on it for 1.3-1.4.

I have just subscribed and I encourage all people complaining about the lack of the definitive guide to do the same ~ ~ . As Fabien wrote in the mailing list, there are lots of really simple things to do - like testing the code from the definitive guide, spotting missing features, etc.
Thank you halfer for the link.

By the way, my feeling is that Fabien forgets to mention one important thing - definitive guide is just ONE place where you can find everything, both basic and advanced. There are many different places you can find information about 1.4, but that's the problem - as I wrote in the first post of this thread - too many distinct sources to find information.

[malas]

i think WIKI is a great web based solution.
the worst thing in WIKIs is that you need to make people add information in a few templates in order for the information to be organized.