I would keep this out of the documentation, like it was. It isn't very helpful to users, especially since there's no clear consensus on that issue. Also, since we are moving to GitHub issues, that will look like #1887, which is completely unrelated (but don't worry about that so much; we'll fix all code issue references when we do the migration).