Potential improvements to symfony docs for 1.3/1.4 [renamed]

[grymuz]

I do,

really - no description for many elements in API, no "The Book", where is form_tag_remote?

I mean, I can't find anything anymore, there are no proper tutorials, some are for doctrine without a propel version and I'm using propel !! What is that? What happened to symfony for anyone?

Really I love symfony, and I've done few projects using it, but I feel like a complete newbie, maybe new symfony is great but the docs suck and it makes the whole framework unusable for me not to mention new users, who must be having fun trying.

For 1.2 they tried to somehow transport previous very good docs (in fact I think it was the best among web frameworks - even better than Djangos) but it was already inconsistent, but since the changes in code weren't so big it somehow worked. Now it's just not what it used to.

Now you can shout at me ~ ~

[Mod: topic renamed to something more constructive! -- halfer]

[Sgurbat]

Unfortunately I agree with you.
I just started studying symfony but I have great difficulty following the examples, the API and tutorials.
I bought "The Definitive Guide to Symfony" but still refers to version 1.0
Learning Ruby on Rails has been great fun but for now I can not say the same for Symfony.

However I will continue to study it.

[skyblaze]

I also think that it is a "shame" that such a great framework is going to a wrong direction as for the docs, I hope the core team will do something about this very soon.

[Sgurbat]

I also think it is a great framework but it is absurd to struggle to find simple examples of code

[skyblaze]

It would be great to have the opportunity to discuss this really important thing with the core team and Fabien Potencier.

[grymuz]

It would be great to have the opportunity to discuss this really important thing with the core team and Fabien Potencier.

I agree.

I didn't write about it just to make some noise, I think that symfony goes the wrong way and maybe it should be noticed byt the core team?

Since François Zaninotto left, the docs are getting worse and worse. I don't know who is responsible for the docs, but maybe there should be a person dedicated just for the documentation like it used to be.

Really I think the documentation was far better than Djangos and Django is said to have great docs.

I don't know how new users may learn symfony? On the forum I find people saying thing like "the learning curve is steep - that's all".

Developers can't study documentation for all different version since 1.0 and try go get to things. It's like Django's motto "Framework for perfectionists with deadlines".

We all have deadlines, and personally when I find myself in a situation when I look two days for a solution to a simple problem which as it turns out doesn't exists - because things were changed and somebody just forgot to mention them....
well - that just doesn't work for me.

It's all sad, since I'm now thinking about moving back to 1.0. Using 1.0.x I made quite big website with lots of custom stuff (not just news and static pages) and it was fast, it was fun and I was using many great things in symfony which made my work eaasier, now they're either changed, or gone or undocumented...

I don't understand this situation

[skyblaze]

It would be great to have the opportunity to discuss this really important thing with the core team and Fabien Potencier.

I agree.

I didn't write about it just to make some noise, I think that symfony goes the wrong way and maybe it should be noticed byt the core team?

Since François Zaninotto left, the docs are getting worse and worse. I don't know who is responsible for the docs, but maybe there should be a person dedicated just for the documentation like it used to be.

Really I think the documentation was far better than Djangos and Django is said to have great docs.

I don't know how new users may learn symfony? On the forum I find people saying thing like "the learning curve is steep - that's all".

Developers can't study documentation for all different version since 1.0 and try go get to things. It's like Django's motto "Framework for perfectionists with deadlines".

We all have deadlines, and personally when I find myself in a situation when I look two days for a solution to a simple problem which as it turns out doesn't exists - because things were changed and somebody just forgot to mention them....
well - that just doesn't work for me.

It's all sad, since I'm now thinking about moving back to 1.0. Using 1.0.x I made quite big website with lots of custom stuff (not just news and static pages) and it was fast, it was fun and I was using many great things in symfony which made my work eaasier, now they're either changed, or gone or undocumented...

I don't understand this situation

i really agree with you....we have to wait and hope for a response from the core team

[Sgurbat]

We all have deadlines, and personally when I find myself in a situation when I look two days for a solution to a simple problem which as it turns out doesn't exists - because things were changed and somebody just forgot to mention them....
well - that just doesn't work for me.

Power quote. ~ ~

[Sgurbat]

It's all sad, since I'm now thinking about moving back to 1.0. Using 1.0.x I made quite big website with lots of custom stuff (not just news and static pages) and it was fast, it was fun and I was using many great things in symfony which made my work eaasier, now they're either changed, or gone or undocumented...

I don't understand this situation

A little Off topic: how can I switch back to the 1.0 version using Pear?

How can I delete the 1.4 version on my PC and install without problems the 1.0?

Tnx to all.

[Sgurbat]

I just switched to 1.0 version of the Framework.

Do you think that is a clever thing switch back to a previous version because docs and support for 1.4 sucks or is better to choose another framework?

It's only a doubt I do not want to create controversy.

I bought "The Definitive Guide to Symfony" so I think I Can follow the 1.0 version pretty well.

Tnx.

[Jimmy]

We all have deadlines, and personally when I find myself in a situation when I look two days for a solution to a simple problem which as it turns out doesn't exists - because things were changed and somebody just forgot to mention them....
well - that just doesn't work for me.

Power quote. ~ ~

Could not agree more...

[Sgurbat]

I switched back to 1.0 to learn but I hope that 1.4 docs will be decent soon.

[skyblaze]

I just switched to 1.0 version of the Framework.

Do you think that is a clever thing switch back to a previous version because docs and support for 1.4 sucks or is better to choose another framework?

It's only a doubt I do not want to create controversy.

I bought "The Definitive Guide to Symfony" so I think I Can follow the 1.0 version pretty well.

Tnx.

That is a really bad thing to hear this. I don't know why Fabien Potencier doesn't take a position on this real big problem about the framework. And then i just want to point out that Fabien Potencier is the responible for the doc for Doctrine project if i'm not wrong and those docs are really amazing

[Sgurbat]

Hi, I didn't understand what you think about my question.

Bye.

[skyblaze]

Hi, I didn't understand what you think about my question.

Bye.

I think it is strange/shame to have to use 1.0 version because the poor docs for 1.4 version

[xplo]

the definitive guide to symfony 1.2 version is still ~ 80% good for 1.3/1.4, you just need to read the "What s new of 1.3/1.4 ( i would read the waht s new 1.2 too... )" to know what has really changed.

But i agree this guide was a big plus for the framework to understand how it just work without searching everywhere on google/forum/random tutorial

[halfer]

Let me step in here and try to modify people's approach to this issue. It has been raised before, somewhat more politely, elsewhere on this forum.

I think it should be beyond doubt that the documentation that is available for symfony continues to be very good, and much effort has clearly been expended on them, right up to the present version. However I tend to agree that there is a missing gap for 1.3-1.4, which is the topic-by-topic approach taken for 1.0-1.2.

However professional programmers don't do themselves any favours by offering their considered opinion that "the documentation sucks". No-one here (I hope) would be rude enough to turn up to Sensio's offices and say that to Fabien, or any of the doc authors, so please try to keep it more constructive. Anyone want to offer educated guesses as to the etymology of the phrase?

Incidentally, whilst I appreciate beginners cannot write documentation, where a gap is identified, anyone can work to fill it. So if any newbies here continue to use symfony, assistance on creating 'the missing manual' would be appreciated by the whole community.

I am not core team btw - just my tuppence worth. First rule of electronic interaction: be nice!

[skyblaze]

Let me step in here and try to modify people's approach to this issue. It has been raised before, somewhat more politely, elsewhere on this forum.

I think it should be beyond doubt that the documentation that is available for symfony continues to be very good, and much effort has clearly been expended on them, right up to the present version. However I tend to agree that there is a missing gap for 1.3-1.4, which is the topic-by-topic approach taken for 1.0-1.2.

However professional programmers don't do themselves any favours by offering their considered opinion that "the documentation sucks". No-one here (I hope) would be rude enough to turn up to Sensio's offices and say that to Fabien, or any of the doc authors, so please try to keep it more constructive. Anyone want to offer educated guesses as to the etymology of the phrase?

Incidentally, whilst I appreciate beginners cannot write documentation, where a gap is identified, anyone can work to fill it. So if any newbies here continue to use symfony, assistance on creating 'the missing manual' would be appreciated by the whole community.

I am not core team btw - just my tuppence worth. First rule of electronic interaction: be nice!

I only ask myself why The core team let this amazing project/framework to decline for the docs problem and why they don't read the forum to reply to posts like this

[halfer]

Well, if you want to alert Fabien to something, drop him an email - fabien.potencier [at] this domain.

I hear what you say about the docs, really I do. But I'd like to be listened to too, and your reply indicates that you've not heard me. In particular, upon (a) the way suggestions are raised, so as not to offend, and (b) the fact that when you use open source software, the whole point is that you get involved. @skyblaze you've been around long enough to be writing some docs, surely? ~ ~

[Andromeda]

I just can agree completely. I'm using symfony extensively for over a year now. And with 1.4 its like learning a new language (exaggerated ~ ~:wink when regarding the time consumtion used to find solutions for simple problems. And I'm getting tired of these days.
I'm right now at a point where I have to make a decission which framework to use for a very big project and I don't know if it's not better to use Zend when it's so hard to estimate the developing time with 1.4 when you get stuck so often on simple problems.

Just two examples for the bad documentation:

I wanted to add a own field to the admin-filter. Only finding the RefCard of generator.yml from 1.0. And after 2hours I'm giving up cause it's not worth for this simple checkbox I want to have.

JQueryReloadedPlugin is like the former ajax-methods in 1.0 and the examples right next to the functions are cool but these examples were not even revised because the function name is still link_to_remote instead of jq_link_to_remote. Thats just a small thing but shows a lot about the handling with docs!

Last thing: really don't understand why fabien is not answering here, it shows me once more that symfony is maybe not the framework for business solutions where you have to plan in advance and rely on something.

[halfer]

@Andromeda, I suggest you send an email to Fabien now, ask him his views, and please post to let us know you have done so.

[hopscotch1978]

+1 to this thread.

@halfer... thanks for being here and responding, that's cool at least.

I think despite the level of whining, people are trying to be constructive here because they care about symfony. If they didn't, they'd simply go away and use something else.

Yes, I agree, some of the whining can get a little heated in a moment of frustration when you're looking for a solution to something that should be really simple..... but I also think the Symfony team shouldn't take this personally.

Symfony does help a lot, but the team would do well to listen to people's complaints. We're not Fabien's friends or family members, we're his customers.... despite the fact that symfony is free.

If I knew symfony inside out, I'd be happy to suggest to Fabien that I'll write documentation, they slap a price tag on it, and I take 20% of sales. But, because I'm new to symfony, I can't. Perhaps someone else will.

[halfer]

I disagree; you are Fabien's customer if you pay Sensio for development work or support services. There seems to be a disparity between what I would have thought are the common ideals of open source culture, and the values reflected in this thread. No-one is "doing symfony a favour" by using it, quite the opposite: the core devs are doing symfony users a massive favour by distributing the software for free. Personally, I would like to see that acknowledged more here.

As far as I know, contributers to the online documentation outside of the core team get 0% of sales - I should think most people use the online versions anyway. If you knew symfony inside out, would you help with the docs, and do it for free? Seems a reasonable deal given the quality of the software you get, unconditionally, for no cost!

Incidentally, nothing I am saying is intended to change people's minds about the need to improve the docs - I am already on record that there are gaps that would be good to resolve. But I do think people need to examine how to raise these issues, as well as the (apparently severe) social disconnect between the rudeness that is casually typed online, versus the rudeness one wouldn't dare using when dealing with someone in person.

[halfer]

@hopscotch1978 - thanks for your thanks, though - 'tis a happy improvement on the last thread ~ ~

I am not a core dev btw - just a user and volunteer, like you!

[hopscotch1978]

@halfer

... fair enough. Didn't know you're not part of the team.

I think everyone's grateful for symfony, but we still need good documentation. I personally have no problem with people getting paid for their work, so I'd be a happier symfony user if it cost some money but came with complete & clear documentation, as opposed to free & somewhat haphazardly documented, which it unfortunately is at the moment.

Aaaaanyway.... back to browsing what's there.

[Andromeda]

Of course we appreciate the work of the core team. Symfony is a great framework, but I think its getting in the wrong direction. For sure are the books and trainings the things they make money with, but without the 'free-users' you cannot sell a product. No testers, no propagation, ... I/My Company would pay for symfony if therefore docu/usability would be improved but all frameworks are for free, so this is not an argument.

[halfer]

@Andromeda - again, I hear you. The point about being unhappy with the docs is now somewhat over-stated.

As a moderator, I do want to help with long-term issues as well as short-term problems, and accordingly I have suggested you can email the core team to get their views. So, please, one person on this thread, take the time to email as I have suggested, and let us know you have done so. It isn't that hard.

[hopscotch1978]

Well, I actually emailed them last week already asking whether there was an up-to-date Definitive Guide available somewhere for Doctrine but didn't hear back. Although it's not impossible to read the old one, learn some basic Propel, and fill in the holes from material elsewhere, it would be more useful have it all in one place.

I'm not disappointed that I didn't hear back. I know people are busy and replying to individual emails takes time. I think if the Symfony team are interested in improving the documentation, rather than "nobodies" emailing them out of the blue, it'd be more useful if a forum sticky or even polldaddy poll was set up to canvas opinions more widely from the community.

[grymuz]

However professional programmers don't do themselves any favours by offering their considered opinion that "the documentation sucks". No-one here (I hope) would be rude enough to turn up to Sensio's offices and say that to Fabien, or any of the doc authors, so please try to keep it more constructive. Anyone want to offer educated guesses as to the etymology of the phrase?

Well, I have to agree, I didn't want to offend anybody. I appreciate the work that people do to make symfony better. I just think that it all wen unmentioned (since it's noticed for sure) - the thing about docs. I guess I was a bit kind of angry about the situation and kind of went off.

So once again, if someone feels offended - I'm sorry and maybe let's try to make something useful out of it all and do something to make the docs better.

So Halfer, what can average Joe do to help with the docs?

[Andromeda]

To be constructive... the manual Symfony Forms in Action was only partially updated for 1.2 and 1.4
http://www.symfony-project.org/forms/1_4/en/
But 1.0 is no longer available but e.g. in Chapter 3 is referred to Chapter 5, which no longer exists... ~ ~

[halfer]

@Andromeda: if you see small, specific problems, I'd suggest a ticket would be the best way to deal with them. If you then find that a ticket goes unactioned for a great deal of time, we can tackle that problem if it arises.

@All: meanwhile I emailed Fabien at the weekend for some general thoughts on the development of the docs. I have apologised for some of the inappropriate comments in advance.

[hopscotch1978]

Fabien, yes, if you do read some of the more heated comments (including from me), it's not personal. Symfony is much appreciated and really excellent. Although the docs could use some work, some of the comments are heated only because they're born out of frustration when in the middle of coding something.

Thanks in advance if some extra time can be put into documentation.

[Sgurbat]

I think that Symfony is a very great framework but after several days and a lot of times spent using it I've decided to left it for now.

It was very frustrating to fight against documentation lack.
I can't spend 2 days (or more) to find a solution for a very simple stupid thing that I have to change in my project.

For now I prefer to continue study Ruby on Rails but when I will see that Symfony docs will be improved I return to study Symfony with very pleasure.

Bye.

[fabien]

Hi all,

As the main author of the symfony documentation, I'm very happy to discover that I "suck". Thanks for all the kind words, I really appreciate ~ ~

You know, symfony is done for free. Yep, everything is free. The code, free, the documentation, free. Trust me, I do my best to provide the best framework and the best documentation possible, but I also need some support.

I say "I" because my name is all over the place in this thread; but keep in mind that symfony is a collaborative effort from many volunteers, all working for free.

So, let's start a constructive discussion about the symfony documentation. Of course, I think the documentation is good, and I think it's way better than the documentation we had in the past. First because, we have more documentation. Then, because we have documentation depending on what you are trying to do:

Want to get started with symfony? read the "Getting started" guide.

Want to learn symfony step by step? read the "Practical symfony" book.

Want to find everything about configuring symfony? Browse the "Reference guide" book.

Want to learn what changed in the recent versions? Read the "What's new?" and "How to upgrade" tutorials.

That's already a lot of documentation for beginners and advanced users.

That said, I'm listening to the complaints. So, if you think things could be better (and I'm sure we can have better docs), give me your ideas.

If you want to talk about the definitive guide, please read the post I have just posted on the mailing-list:

http://groups.google.com/group/symfony-users/msg/1cc6ba22776 a6b09

Fabien

[hopscotch1978]

That's excellent to hear... thanks Fabien.

[halfer]

@Sgurbat - thought you'd dropped to version 1.0? I use that version every day, still, and have found the documentation to be excellent. Many people use 1.2 and the same applies to them.

We won't mind if you use Rails instead (I hear it is a great framework, I intend to try it myself) but I do think you are giving up too easily.

[Sgurbat]

@Sgurbat - thought you'd dropped to version 1.0? I use that version every day, still, and have found the documentation to be excellent. Many people use 1.2 and the same applies to them.

We won't mind if you use Rails instead (I hear it is a great framework, I intend to try it myself) but I do think you are giving up too easily.

Thanks for your post.

I didn't want to make some noise or offend anyone.

It was just a my opinion and I said that however I think that Symfony is a great framework.

Bye.

[halfer]

Sure, I was just surprised that you were giving up. I was concerned that while people were voicing their concerns about the docs for 1.3 and 1.4, you would have been unaffected if you were using version 1.0. The docs are great for that version, IMHO at least.

[rattusdatorum]

so, I am pretty newbie on the whole thing, so I take my shot...

I just head some ideas floating around in the bath tube...

1) Donations, since many seem to use symfony professionally (as freelancers I guess) donations shouldn't be much of a problem. Altough, I must admit the donation button is quite good hidden.
Maybe everyone, who complained here did donate already a bit or even a huge pile - my apologies. I didn't donate anything so far, yet since I prefer donating to institutions that I know and helped, I guess I will go for it.

2) Specific "documentation requests" via tickets/forum. If there a specific problems and nobody can solve them and you are an experienced symfony developer - not some newbie like me - then there should be a way to find a solution and it should be documented properly in the forums. Maybe a subforum with the question/problem and result. Or on the main documentation page: Challenges + Solutions (in a wiki fashion?) ? (It kinda reads like many people solved many problematic tasks already.)

3) Probably combining 1 & 2?

so I am pretty green on this, yet, if I catch some flak maybe I learn something ~ ~

---

my view on the documentation (Notice: I only know the jobeet tutorial til day 13 + a few other days so far.)
My impression is that is similar to other tutorials, right there at the trenches, which is quite good in some ways, yet terrible for other things - from the trenches it is hard to see the whole frontline.
I basically miss an "overview", I can't see how the things work together. Symfony appears to be like many black boxes to me, which is okay, but I don't where these black boxes interact and which black box to use for what. I made some notices during the tutorial and now picking up some things, I hope I can provide such an overview. A friend you dug into a few frameworks had the same problem. Since symfony is that mighty and has high level abstraction it is utterly confusing for newbies what is going on from the joobeet trench.

so now I am back at watching Band of Brothers ~ ~ yeah, so much for the trench metaphors.

[xplo]

for info Fabien updated all the chapter of the reference book to sf 1.4 ~ ~