Wouter, I like your post and your job (together with the other contributors) on the docs.
It might help make things move forward. Thanks. I'll be happy to contribute to the docs review when the process is in place. Cheers, Victor On Friday, March 1, 2013 3:00:59 PM UTC+1, Wouter J wrote: > > Symfony2.2 is released today[1]. As said in the blogpost "it is the first > Symfony2 release that was driven by our new release process". > > I think it is good to have some review of it, see what can be improved and > what was really awesome. When something is introduced, you always know that > the first one doesn't go as expected. > > ---------------- > > My points, as a core documentation contributor: > > At the start of the stabilization phrase, we've got a great topic by Victor > which was talking about how we can improve the documentation[2]. There were > some really great ideas in there, two of them: > > - A dochunt day (or even multiple days) > - Rereading most important docs by core code contributors > > Ryan even came with a really great target[3]: > > > 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. > > Well, to be honest none of these came true... > > ## Target A > > We really need some dochunt days and days where the core code community is > involved in the documentation. I don't know every feature of the code, I > already fixed the Routing setting changes, but there are a lot of other > things > to be checked as well. > > ## Target B > > We don't have documentation for every 2.1 and 2.2 feature, we even don't > have > documented every feature for 2.0! > > We be more strict with our process of merging into the code. A feature > should > **never** get merged without having the documentation **ready**, meaning > not > creating a ticket *'you should document this because I have added that > feature > in the code'*, but actually having a PR which says *'this is the > documentation > for that feature'*. That doesn't need to be done by the creator of the > feature > (while that is the best option), he can create an issue and some of the > core > doc guys can pick that up. > > One of the six reasons to choose Symfony[4] is 'Resources'. Saying "an > undocumented line is a line that does not exist" said a little bit > ironically > to me now... > > ## Target C > > I have gone through all the 128 issues on github and put a comment saying > it > needs to be closed or get some tags. Most of them are tagged/closed, but > not > all (it would be much easier if I could tag myself though...). > > That means we've a great overview in what needs to be done and some > problems > with the docs. It also means people can easily spot a simple thing to do if > they have some time. They can also spot hard things if they really want to > deserve the famous 'Doc Contributor Badge' ;-) > > ---------------- > > I hate it to say only negative things, so it would like to say that I will > never stop loving the Symfony framework/community/documentation. > > Some great articles and features were added (for instance, the Config & > HttpKernel component documentation); we have got a new merge process for > the > documentation, which helps us and don't make it hard to contribute; with > the > help of the really great @ricardclau we have almost every format documented > everywhere; ect. > > ---------------- > > ## Conclusion > > I think it's time to put some serious work in the documentation. We > shouldn't > only be sure the framework itself is stable enough before a release, we > should > also be sure that the documentation is stable enough. > One of the big 'cons' I have with ZF2 is that it's documentation is too > pour, > please don't let that happen with the Symfony docs. > > [1]: http://symfony.com/blog/symfony-2-2-0 > [2]: > https://groups.google.com/forum/?fromgroups=#!topic/symfony-devs/-6HAQgAB2LY > [3]: > https://groups.google.com/d/msg/symfony-devs/-6HAQgAB2LY/uBSx8uYJQdQJ > [4]: http://symfony.com/six-good-reasons > -- -- 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.
