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
