What to do with old/obsolete documentation

While recently reviewing the content of the plugins handbook, I discovered some content that is no longer current (specifically, this page that deals with the term splitting fix that happened four years ago as part of the automatic upgrade process for 4.2).

After some discussion with the documentation team it became clear we lack a unified way to identify which documentation is obsolete, and what to do about it when it is. As a result, old docs end up hanging around in a position of implied accuracy, potentially adding to confusion.

To begin with, we need to answer these questions:

  1. What is considered obsolete? Is it even possible to come up with a general rule for this?
  2. Who decides if a page is obsolete?
  3. What do we do about it? (see below)

Once the obsolete docs are identified, we need to decide what to do with them:

A. Do nothing (this is here for completeness’ sake. This is not a valid path forward.)
B. Delete them
C. Leave them in place and mark them as obsolete as of a specific WP version or date
D. Move them to an “archive” or “legacy” section and mark them as obsolete as of a specific WP version

Depending on the decision this will require some or all of the following:

a. standardized markup to appear at the top of a page, to clearly identify that this entire page is considered legacy (hopefully via a shortcodeShortcode A shortcode is a placeholder used within a WordPress post, page, or widget to insert a form or function generated by a plugin in a specific location on your site.)
b. standardized markup to clearly identify a specific section of a page that is is considered legacy
c. a place in each handbook for legacy documents, along with markup to clearly identify them as such

I suggest the following

  1. The identification of a page or page partial that should be discussed can be put forward by anyone
  2. The “owner” of the handbook (or whatever) along with anyone else of interest can discuss the validity of the content in question and determine if it should be adjusted.
  3. If it has been determined that the content is no longer relevant, the correct action (one of B. C. or D.) can take place.

I realize this may seem like navel gazing but if we can at least come up with a general consensus on how to handle this situation, it will provide a starting point.