Let's take a milestoned issue: #2719 In 2.2, the routing system has changed and we use a lot of the deprecated methods in the documentation. Imagine the 2.2 branch was deprecated, isn't it completly wrong to not update that version but only update it in 2.3, as if the change was made in Symfony 2.3? We then have not working code in our documentation, just because we kept strict to the deprecation rule.

I think you can start deprecating things completely after all big things are fixed/documented. You can't deprecated the 2.1 version of the sf core if you know that it has some big bugs.

While we have a great doc team, we can't fully keep up with the core code (as that team is still much bigger). That's why I think we should not fully deprecate a doc branch, until all milestoned issues are fixed. Once a branch is fully deprecated, it needs to be fixed on the oldest maintained branch.

BTW, I recently removed the wrong milestones from issues, as some issues were milestoned but didn't really belong to a specific version,