Le samedi 5 janvier 2013 10:08:31 UTC+1, Victor Berchet a écrit : > > 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 >
I disagree with you. If you do that, you loose the way to know when a feature was introduced. Of course, you can guess it by browsing the git history, but it is not user friendly. More over, some times, your read the master documentation, see a new feature and said 'oh this is what I need. I may upgrade my vendor to get this feature" > 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
