Ryan, Your action plan sounds really good to me.
I'd like to hear your opinion on "versionadded" vs branch specific doc. Cheers, Victor On Sunday, January 6, 2013 12:25:45 PM UTC+1, weaverryan wrote: > > 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<javascript:> > > 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 symfon...@googlegroups.com<javascript:> >> To unsubscribe from this group, send email to >> symfony-devs...@googlegroups.com <javascript:> >> 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
