Contrib.social

Figure out a plan for dealing with deprecated documentation

Open on Drupal.org →
Created on 3 March 2021, over 4 years ago
Updated 26 March 2025, 4 months ago

Documentation location/URL

On #2989810-43: Make it clear how to report docs issues and find pages that need attention → (and other comments, @hansfn brought up a good question:

What is our plan for deprecated documentation?

... after someone marks a page as deprectated (explaining why in the comment of course) what should happen? Should we discuss it further on the page, create an issue, just delete it if we have the power to do so?

Proposed resolution

Add the following to {insert page}.

Deprecated documentation

Deprecated documentation is documentation for an outdated way of doing something. There are several ways to deal with deprecated documentation:

  • If the old documentation should never be used under any circumstances, edit the page so that it documents the new way of doing things.
  • Alternatively, if the old documentation should never be used and a new page already exists, delete the old page and redirect its old URL(s) to the new page.
  • If the old way of doing things still applies in some circumstances (such as when you are using an older but still supported version of the software), create a new page with the new documentation, and mark the old one as deprecated.

Marking a page as deprecated

  1. Change the page status to Deprecated
  2. Add a note in the revision log explaining briefly why it is being deprecated
  3. Add a section at the top of the page explaining the deprecation. This section should include:
    • What version(s) or condition(s) the page can still be used for and what it won't work at all for.
    • When it was deprecated and optionally why.
    • A link to the page telling you what to do instead, or at a minimum, a brief description of what do to instead.
    • If there are plans to delete the page at some point, when that would happen.

    Sample:
    The information in this page was deprecated on March 1, 2021. It will still work on Drupal 8.x and 9.x sites, but it will stop working in 10.x. If you are using Drupal 9.x or later, you are advised to ___(link to newer docs or description of what to do)_______ instead. This page will be removed when Drupal 11 is released.

Remaining tasks

🌱 Plan
Status

Active

Component

Policies and Procedures

Created by

🇺🇸United States jhodgdon Spokane, WA, USA

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • Comment 4 months ago →
    🇳🇿New Zealand quietone
  • Comment 4 months ago →
    🇳🇿New Zealand quietone

    What to do if the old documentation has no replacement and should be deleted? Say, it is out of date and the content has been re-arranged or it is a duplicate>

  • Comment 4 months ago →
    🇺🇸United States eojthebrave Minneapolis, MN

    If it's a duplicate I think we should feel free to delete it and redirect to the other page. And, if it has no replacement and should be deleted ... delete it I guess? I don't think we should be trying to keep something around forever just for archival purposes. Or ... if we do have to do that it should be placed into some very obviously "archived" section.

  • Comment 16 days ago →
    🇩🇰Denmark ressa Copenhagen

    To get deprecated pages out of the way, and give them less focus, until a decision has been made (move, delete, update, etc.), would it be possible to place them last, at the bottom of guides?

    I think the first three "Page status" should not affect the order.

    • No known problems
    • Needs review
    • Needs work
    • Deprecated << Place these at the bottom

    As an example, see https://www.drupal.org/docs/managing-site-performance-and-scalability/si... →

    The deprecated "Drupal Services" page is shown above a fresh, relevant page "Self-hosted monitoring tools".

    Additionally, we could consider changing the typography of deprecated pages slightly in a guide, to convey the "less importance" (smaller font, grey background), maybe even under a "Deprecated" heading?

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024