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:

What is considered obsolete? Is it even possible to come up with a general rule for this?
Who decides if a page is obsolete?
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

The identification of a page or page partial that should be discussed can be put forward by anyone
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.
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.

Jonathan Desrosiers 3:20 pm on December 17, 2020
I am very much against removing any documentation like the page used as an example for several reasons:
- It clearly states the versions the considerations apply to.
- It documents how WordPress has behaved in the past.
- It documents the history and a journey to the current state, which is often important to understand why something is how it is.
- Information like this is always relevant, even if referenced less and less over time.
- Often times, pages that document processes and changes like this leave remnants behind. These pages are essential to understanding what those remnants were used for in the past. For example, why is there still a `wp_terms` and `wp_term_taxonomy` table if terms are no longer shared (see #30262).
Any documentation that is outdated because it applies to specific versions or version ranges should be updated to be explicit about which versions the docs apply to.

All this said, I would not be opposed to including a disclaimer at the top that says “this documentation applies to a much older version of WordPress. While it still may be relevant, it’s possible some parts of the documented behavior has changed since.” at the very top, similar to the “This pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party has not been updated in over 2 years” one on plugin pages. I guess that would be a form of option D as suggested above.

I also would not be opposed to consolidating this type of documentation under a “Version Specific Documentation” top level page.
Hauwa Abashiya 4:08 pm on December 18, 2020

I’m not sure what is the best solution but I am against deletion. We (training team) have a number of lesson plans on learn.wordpress.org that reference the content in handbooks. After having to update all the broken links for screen-shots we would not want to go through that process with links to docs.

In the past we have reviewed our lesson plans on a quarterly basis to check they are in line with the current version of WordPress so I guess option D would work. As the team is regrouping we are keen on collaborating with #metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. and #docs (and any other teams) regarding how best to manage this.https://make.wordpress.org/docs/2020/12/17/what-to-do-with-old-obsolete-documentation/#
Akira Tachibana 8:09 am on December 20, 2020

I agree @desrosj‘s comment. IMHO we may remove non-supported version’s description (but history is important. Yes, I think so, too.)

Also, we may consider to add initial published date and modified date of each page. People sometimes forgot adding effective WordPress version, so it will help which document is relative new or old.
Estela Rueda 2:31 pm on January 11, 2021

Personally, I don’t care for historic pages, but they seem to be a great deal for others. Thus I’ve also been looking into solutions for the documentation and I was thinking of adding an “archive” section at the end of the handbook and add all the unsupported/old/ obsolete versions there?
Milana Cap 10:40 am on January 25, 2021

I think it’s difficult to treat all outdated info equally. Some info we might not care about the moment it became obsolete but some could be very useful for a long time after going out of date. Therefore, I think we can’t really create unified way of treating them if that way is removing them completely.

Also, I wouldn’t create Archive and move them there as it might become confusing if removed from its context.

Personally, I’d love some kind of versioning system where you would have the same page offered for each WordPress version and selecting any version other than current would show content that was relevant for that version (perhaps even with the diff view).

With current state, I’d go with leaving content where it is. If it’s just the part of the page I’d go with b option (standardized markup to clearly identify a specific section of a page that is is considered legacy); if the whole page is out of date then I’d go with option a (standardized markup to appear at the top of a page, to clearly identify that this entire page is considered legacy). I might go even that far to have a completely different CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. for obsolete pages in case someone miss the notice on the top of it (like people missed the same notice for Code reference at Codex for a very long time).

Want to get involved?

Weekly meetings

What to do with old/obsolete documentation

Want to get involved?

Weekly meetings

Share this: