Hi guys and Victor! First, I also used symfony1 because of it's documentation, so I'm with you 100% on making the docs great :). I think the docs can really benefit from some bug-hunt days and, overall, using some time to "stabilize" as you said during the 2.2 stabilization period. Here's the status on some things:
1) Most of my time is spent reviewing, merging and updating pull requests. I rarely have enough time to actively check issues or make updates. That's great in some ways - the community is super-active. 2) A small (but awesome) group of people has recently started to go through the issues, notify if they should be closed / create PR's if needed, etc. But, a bigger short-push is still needed to really tackle this to a small number. 3) The combination of the 2.1 BC-breaks being somewhat large, and not requiring doc PR's for code PR's (something I think now is *really* amazing), left some holes in the 2.1 changes as you noted. I think these are quite few, but a one-time review to catch up will help. For example, on the "equals" change, we have that updated in 2 docs, but we missed it in custom_provider. 4) The original large chapters were originally created on average about 24 months ago (way before 2.0 came out). We've now had 2 years to update our philosophies and best-practices and to learn much more about where people have trouble. It's quite a bit of work, but I think having core people re-read these chapters now - at least in order to create issues about what we think should be changed - would be a huge help. I think we'll only need to do this once. In line with Victor, here's what I propose: a) I can prepare individual issues under a milestone of documents that I feel could benefit from a full-reading from some core member. With that, we can hopefully motivate a push from the core community to tackle one or two of those tickets b) We organize a single bug-hunt day - perhaps on a Saturday a month from now - and advertise it on the main blog. Between now and then, I (and hopefully the guys that have been helping me) will continue to clean up the issues (most notably, closing things that are invalid or already done). On that day, we can focus people on the 2.1 branch specifically (because then they'll catch both bugs - which can be fixed on 2.0 - and out-of-date stuff) and have them tackle issues, re-read certain doc, etc etc. The goal - and I think this is your point Victor - would be that when 2.2 comes out, we're feeling like the documentation (a) has been re-read and updated for latest philosophies, (b) is fully current on 2.1 and 2.2, and (c) has its issues at a low level. Thoughts? Thanks! Ryan Weaver US Office Head & Trainer - KnpLabs - Nashville, TN http://www.knplabs.com <http://www.knplabs.com/en> http://knpuniversity.com Twitter: @weaverryan On Sat, Jan 5, 2013 at 3:08 AM, Victor Berchet <vic...@suumit.com> 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 > > > -- -- 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
