Hi Wouter and everyone else!

I think you've said some nice things here, including how you celebrated
many of the great things that we've accomplished with the docs recently
(quite a bit with your help):

** Wins **

 a) We have more activity on maintaining the docs (commenting on PR's,
following up on issues, small PRs to close issues) than ever before. This
is HUGE.

b) We have a new PR documentation format, which helps us track things
(stolen in principle from the code format)

c) The docs are not out-of-date. Yes, there are certainly things that can
be found, but we work hard at this, and the community is helping us
constantly. I don't want people to get the impression that the docs are
falling behind - it's simply not true :).

d) Changes to code are not being merged until there is at least an issue on
the docs. This is probably the most important change.

You're of course also right that some goals that we set out haven't been
achieved yet, but they're still needed! I have the following takeaways that
I'll put on my immediate list. I would have liked to do these earlier, but
time isn't always there :). The nice thing about the docs is that we can
make big changes whenever we want to (unlike the code):

** Todo Next **

1) A Dochunt day (and maybe more in the future). This has been an idea for
awhile, I'll put some plans together and run them by Fabien

2) A re-read of the core docs by code contributors. This is also on my list
to get organized

3) Continue to not merge in code changes without at least an issue on the
docs <--- remember, I said this was important :)

** Docs History **

The ideal goal of course is for the docs to be totally up to date and
document everything. With the items above, we will get closer and be able
to maintain better. But this is also only possible starting very recently
as Symfony is approaching its first LTS. The documentation started in
mid-2010, about 2 full years before 2.0.0. And since it's not feasible to
write the documentation before the framework, it's been a bit of a catch-up
game since then (and we have caught up both in accuracy and
features-documented). I think we have some great plans in place to continue
to stay current with Symfony's development, and with a few extra pushes,
we'll close more of the gap that's been there since the beginning.

I'll ping back when I have more details on the items above. Thanks for
continuing to bring this up - I'm very happy to see the documentation under
a microscope - it should be - and I'm happy to be part of the process to
make it great.

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 Fri, Mar 1, 2013 at 8:00 AM, Wouter J <jong.de.wou...@gmail.com> 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.
>
>
>

-- 
-- 
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.


Reply via email to