Should deprecated (still active) behavior be documented?

Hello rails friends,

I’d like to propose that all documentation contributions for deprecated behavior be considered. I personally find documentation of deprecated behavior to be useful. I don’t think that a docs contribution should be rejected solely because it relates to deprecated behavior.

Such documentation should make it clear that the behavior is deprecated. Removal of such documentation should not be considered until the behavior is actually removed.

Does this make sense?

This sounds very abstract yet specific to cases you’ve seen. Where have you found documentation to be missing, rejected or prematurely removed?

I’m curious about this as well, but I am also +1 for Jared’s proposal. There’s a lot of Rails terra incognita.

Just to clarify the thing that’s great currently is that maintainers get to move on quickly without having the old docs around. Though I’m paraphrasing and would need specific cases to verify this.

Curious too if this is solved via the versioned API docs? For example, https://api.rubyonrails.org/v6.0.0/classes/Mail.html