This forum is in READ-ONLY mode.
You can look around, but if you want to ask a new question, please use the new forum.
Home » development » Documentation » tutorials, books and guides
tutorials, books and guides [message #87523] Thu, 29 October 2009 01:09 Go to next message
tkoomzaaskz  is currently offline tkoomzaaskz
Messages: 101
Registered: February 2008
Location: Poland
Senior Member
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?


symfony-world blog
Re: tutorials, books and guides [message #90618 is a reply to message #87523 ] Wed, 30 December 2009 09:46 Go to previous messageGo to next message
nedy  is currently offline nedy
Messages: 1
Registered: December 2009
Junior Member
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.).
Re: tutorials, books and guides [message #90635 is a reply to message #87523 ] Wed, 30 December 2009 11:51 Go to previous messageGo to next message
halfer  is currently offline halfer
Messages: 9535
Registered: January 2006
Location: West Midlands, UK
Faithful Member
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.


Remember Palestine
Re: tutorials, books and guides [message #90675 is a reply to message #87523 ] Thu, 31 December 2009 00:19 Go to previous messageGo to next message
tkoomzaaskz  is currently offline tkoomzaaskz
Messages: 101
Registered: February 2008
Location: Poland
Senior Member
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 Sad.

The symfony project is getting bigger and bigger...


symfony-world blog
Re: tutorials, books and guides [message #90828 is a reply to message #90675 ] Mon, 04 January 2010 22:34 Go to previous messageGo to next message
DBA_Alex  is currently offline DBA_Alex
Messages: 257
Registered: July 2008
Location: North Carolina, USA
Faithful Member
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.


Currently Using
---------------------------
Symfony 1.4/Doctrine 1.2
MySQL 5.1
Re: tutorials, books and guides [message #91380 is a reply to message #87523 ] Wed, 13 January 2010 18:21 Go to previous messageGo to next message
skyblaze  is currently offline skyblaze
Messages: 205
Registered: January 2008
Faithful Member
I also think that a "Defenitive guide" updated for the 1.4 version is a must!!
Re: tutorials, books and guides [message #92258 is a reply to message #91380 ] Tue, 26 January 2010 21:18 Go to previous messageGo to next message
malas  is currently offline malas
Messages: 154
Registered: December 2007
Location: Vilnius, Lithuania
Senior Member
+1

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

for future releases documentation should be a must.


jaglas.lt - professional web developers.
Re: tutorials, books and guides [message #92266 is a reply to message #92258 ] Tue, 26 January 2010 23:06 Go to previous messageGo to next message
halfer  is currently offline halfer
Messages: 9535
Registered: January 2006
Location: West Midlands, UK
Faithful Member
malas wrote on Tue, 26 January 2010 20:18

+1

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

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!


Remember Palestine
Re: tutorials, books and guides [message #92272 is a reply to message #92266 ] Tue, 26 January 2010 23:41 Go to previous messageGo to next message
malas  is currently offline malas
Messages: 154
Registered: December 2007
Location: Vilnius, Lithuania
Senior Member
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 Smile
it's just my opinion Smile


jaglas.lt - professional web developers.
Re: tutorials, books and guides [message #92277 is a reply to message #87523 ] Wed, 27 January 2010 01:26 Go to previous messageGo to next message
halfer  is currently offline halfer
Messages: 9535
Registered: January 2006
Location: West Midlands, UK
Faithful Member
@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 Smile.

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! Very Happy

[Updated on: Wed, 27 January 2010 01:37]


Remember Palestine
Re: tutorials, books and guides [message #92292 is a reply to message #92277 ] Wed, 27 January 2010 09:04 Go to previous messageGo to next message
tkoomzaaskz  is currently offline tkoomzaaskz
Messages: 101
Registered: February 2008
Location: Poland
Senior Member
Guys, please calm down Smile

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 Smile ) 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??

[Updated on: Wed, 27 January 2010 09:06]


symfony-world blog
Re: tutorials, books and guides [message #92299 is a reply to message #87523 ] Wed, 27 January 2010 10:27 Go to previous messageGo to next message
malas  is currently offline malas
Messages: 154
Registered: December 2007
Location: Vilnius, Lithuania
Senior Member
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 Wink


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 Smile pretty straightforward way, but it works very well here Smile


jaglas.lt - professional web developers.
Re: tutorials, books and guides [message #92300 is a reply to message #92299 ] Wed, 27 January 2010 10:37 Go to previous messageGo to next message
tkoomzaaskz  is currently offline tkoomzaaskz
Messages: 101
Registered: February 2008
Location: Poland
Senior Member
malas wrote on Wed, 27 January 2010 10:27

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 Smile pretty straightforward way, but it works very well here Smile

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?


symfony-world blog
Re: tutorials, books and guides [message #92301 is a reply to message #92300 ] Wed, 27 January 2010 10:45 Go to previous messageGo to next message
malas  is currently offline malas
Messages: 154
Registered: December 2007
Location: Vilnius, Lithuania
Senior Member
From my point of view, i was not rude Smile
and if the western europeans want to be democratic they should respect and understand other cultures Wink this is a neverending philosophical discussion Smile

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


jaglas.lt - professional web developers.
Re: tutorials, books and guides [message #92306 is a reply to message #87523 ] Wed, 27 January 2010 11:51 Go to previous messageGo to next message
halfer  is currently offline halfer
Messages: 9535
Registered: January 2006
Location: West Midlands, UK
Faithful Member
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 Smile

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.


Remember Palestine
Re: tutorials, books and guides [message #92312 is a reply to message #92306 ] Wed, 27 January 2010 12:22 Go to previous messageGo to next message
tkoomzaaskz  is currently offline tkoomzaaskz
Messages: 101
Registered: February 2008
Location: Poland
Senior Member
halfer wrote on Wed, 27 January 2010 11:51

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 Smile. 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.


symfony-world blog
Re: tutorials, books and guides [message #92315 is a reply to message #92306 ] Wed, 27 January 2010 13:23 Go to previous message
malas  is currently offline malas
Messages: 154
Registered: December 2007
Location: Vilnius, Lithuania
Senior Member
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.


jaglas.lt - professional web developers.
Previous Topic:Source code for form example on "More with Symfony" book
Next Topic:How to format an sfWidgetFormChoice in multiple columns
Goto Forum:
  

powered by FUDforum - copyright ©2001-2004 FUD Forum Bulletin Board Software