An other idea to improve the documentation: make the examples executable (ie add a Symfony playground).
There are things like phpassist.com and phpfiddle.org. The former looks very promising and should be able to support the Sf2 framework soon. To me, there is no way to go for a closed source solution - that's no pressure Amit :) I think it could be something really interesting to draw more attention to Sf2. Thoughts ? On Saturday, January 5, 2013 10:08:31 AM UTC+1, Victor Berchet wrote: > > The Symfony2 documentation is already quite good and this is mostly due to > the awesome job done by Ryan[1] but I think think we can (and should) do an > even better job - documentation is probably what made me pick Symfony1 as > my favorite PHP framework some years ago. > > Until some months ago, there was only a single branch for the whole > doc[2]. We came up with the "versionadded" tag to differentiate things that > were only applicable to some versions. As of today, the docs use the same > branching schema as the symfony repo and we have mix of "versionadded" and > branch only documentation. > > I would love to see the complete drop of "versionadded" tags in favor of > only branch specific versions of the doc. That would probably mean a harder > work for maintainers (sorry for that Ryan), but it would become less > confusing for the users - you should also note that absolutely no > guidelines are given on when to use the "versionadded" tag in the > contributing docs[4]. > > We are now only days away from the 2.2 feature freeze milestone and that > would be a great first task for the coming 2-month stabilization period. > > As there is no great framework without a great documentation, we should > also use the stabilization period to review the docs and fix most of the > 146 pending issues. > > Let me give you some examples of what could be important things to fix in > the doc: > - security configuration: the doc still promotes using path[5] while using > routes should be preferred (i18n) - I think this is supported since 2.1, > - security: stop promoting *wrong* configuration - more details in a > coming "Not in Symfony2.2"[6] episode, > - security, cookbook chapter "How to create a custom User Provider": the > equals method is no more part of the UserInterface since 2.1 > - ... > > A couple of doc hunt days would be really helpful during the stabilization > period. We should make sure to plan who is reviewing what to make sure all > the chapters get reviewed. > > After the stabilization period, the doc should hopefully be in a great > shape. Going forward, that would be cool to merge Symfony PRs only when > they have a matching docs PR (and unit tests, but that's an other topic). > > What do you think ? > > [1] https://github.com/weaverryan > [2] https://github.com/symfony/symfony-docs > [3] > https://github.com/symfony/symfony-docs/blame/master/book/security.rst#L410 > [4] > http://symfony.com/doc/current/contributing/documentation/overview.html > [5] > http://symfony.com/doc/master/book/security.html#using-a-traditional-login-form > [6] https://gist.github.com/aa9df0383848e86af7ad > > -- -- If you want to report a vulnerability issue on Symfony, please read the procedure on http://symfony.com/security You received this message because you are subscribed to the Google Groups "symfony developers" group. To post to this group, send email to symfony-devs@googlegroups.com To unsubscribe from this group, send email to symfony-devs+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/symfony-devs?hl=en --- You received this message because you are subscribed to the Google Groups "Symfony developers" group. To unsubscribe from this group and stop receiving emails from it, send an email to symfony-devs+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
