Add Sunsetting content guide

files/en-us/mdn/writing_guidelines/howto/creating_moving_deleting/index.md

@@ -106,6 +106,9 @@ For example, let's say you want to move the entire
 
 Documents should only be removed from MDN Web Docs under special circumstances. If you are thinking about deleting pages, please discuss it with the MDN Web Docs team on the [MDN Web Docs chat rooms](/en-US/docs/MDN/Community/Communication_channels#chat_rooms) first.
 
+> [!NOTE]
+> This section covers deleting individual pages or page trees. If you need to retire an entire section of MDN content, consult the [Sunsetting content](/en-US/docs/MDN/Writing_guidelines/Howto/Sunsetting_content) guide.
+
 Deleting one or more documents or an entire tree of documents is easy, just like moving pages, because we've created a special command that takes care of the details for you:
 
 ```bash

files/en-us/mdn/writing_guidelines/howto/sunsetting_content/index.md

@@ -0,0 +1,95 @@
+---
+title: How to sunset a section of content
+short-title: Sunsetting content
+slug: MDN/Writing_guidelines/Howto/Sunsetting_content
+page-type: mdn-writing-guide
+sidebar: mdnsidebar
+---
+
+This article describes the process for retiring entire sections of MDN Web Docs content, known as _sunsetting_. Sunsetting is different from [deleting or moving individual pages](/en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting); it applies when a whole section is no longer actively maintained, relevant, or aligned with MDN's goals and needs to be retired in a planned and transparent way. Sunset content is not permanently deleted — it is always archived in the [MDN Museum repository](https://github.com/mdn/museum).
+
+Sunsetting is a very rare occurrence, and the process will differ depending on the circumstances. This guide provides an overview of when and how to sunset a section, and the steps to follow to do so responsibly. For a list of sections that have already been sunset, see [Sunset content](/en-US/docs/MDN/Writing_guidelines/Howto/Sunsetting_content/Sunset_content).
+
+## When to consider sunsetting content
+
+You may want to propose sunsetting a section of MDN Web Docs content if any of the following apply:
+
+- The technology is deprecated or no longer relevant to the web platform.
+- The section duplicates information better maintained elsewhere (such as an official documentation site for a framework).
+- The section does not align with [MDN's content strategy](/en-US/docs/MDN/Writing_guidelines/What_we_write#topics_that_belong_on_mdn_web_docs).
+- The maintenance cost outweighs the value to users, as indicated by usage data and user feedback.
+
+Sunsetting should always be a deliberate, visible process. Large-scale removals should never happen without discussion or notice. The final decision to sunset a section lies with the MDN team.
+
+> [!NOTE]
+> If you want to remove individual pages rather than an entire section, consult our [Deleting pages](/en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting#deleting_pages) guide. For guidance on labeling individual features as deprecated, see [How to label a technology](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete).
+
+## The sunsetting process
+
+Sunsetting a section of MDN Web Docs content involves two phases: reaching an agreement and then removing the content.
+
+### Phase 1: Decision process
+
+Sunsetting must be agreed upon by the MDN team and partners. Discussion may happen in our [communication channels](/en-US/docs/MDN/Community/Communication_channels), via a [GitHub discussion](https://github.com/orgs/mdn/discussions), and/or in our editorial calls (held every two weeks).
+
+If a section is seriously being considered for sunsetting, a GitHub discussion must be opened to capture the decision and process. The discussion should be clear about:
+
+- The reasoning for removal.
+- The impact of the removal.
+- Relevant stakeholders are aware and have been consulted.
+- Alternative approaches have been considered.
+
+In some cases, the decision may also involve **gathering feedback from MDN users**. This can include:
+
+- Running a user survey.
+- Asking for feedback via GitHub or other [MDN communication channels](/en-US/docs/MDN/Community/Communication_channels).
+
+The goal is to confirm that the section is no longer meeting user needs and that there is no clear path to its sustainable maintenance.
+
+If an agreement to sunset a section is reached, a timeline should be set — typically between **3 and 6 months**. The reasons and timeline should be recorded in the GitHub discussion. It should be clear in the discussion that the content will be archived, not permanently deleted.
+
+If a decision is reached _not_ to sunset, this should be communicated along with reasons via the original communication channel.
+
+### Phase 2: Removing content
+
+Once agreement has been reached, follow these steps to remove the content.
+
+#### Add a sunsetting notice banner
+
+Add a [note banner](/en-US/docs/MDN/Writing_guidelines/Page_structures/Banners_and_notices) to the top of _every article_ in the section being sunset. The banner should clearly state:
+
+- That the section is being removed from the website.
+- The expected removal timeframe and date.
+- That the content will be archived.
+- A link to the GitHub discussion for more details.
+
+Use the following template:
+
+```md
+> [!NOTE]
+> This section of MDN is no longer being maintained and will be removed from the website in 6 months (by MONTH YEAR). The content will be archived in the [MDN Museum](https://github.com/mdn/museum). See [this discussion](LINK) for further information.
+```
+
+This notice ensures transparency and gives users time to adjust.
+
+#### Archive and remove the content
+
+After the agreed-upon sunsetting period has passed, the content can be removed from MDN Web Docs as follows:
+
+1. **Archive the content.** Copy the section to the [MDN Museum repository](https://github.com/mdn/museum) for archival purposes. Keep the content in a directory that matches the original URL path. For example, content at `https://developer.mozilla.org/en-US/docs/Games` would go in a `/docs/games/` directory in the museum repository. This preserves MDN's content history while keeping deprecated material off the active site.
+
+2. **Remove the content and add redirects.** Use the [`delete` command](/en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting#deleting_pages) to remove the pages and set up redirects. Redirects should point users to the most relevant alternative content if available. If there is no suitable alternative, redirect to the MDN Web Docs homepage.
+
+3. **Clean up references.** Remove or update any references to the sunset section across MDN including sidebar definitions, landing pages, and cross-links from other articles. Adding redirects (see Step 2) will prevent broken links, but it is best practice to update the referring content directly.
+
+4. **File an issue for UI updates.** Some sections of the website UI — such as navigation menus and homepage sections — are not part of the `content` repo and are instead managed by the platform team. File an issue in the [mdn/fred](https://github.com/mdn/fred/) repository to check whether any UI changes are needed to remove references to the sunset content. If they are, coordinate the content removal and the UI update so they are deployed at the same time.
+
+> [!WARNING]
+> Do not permanently delete content without archiving it first.
+
+## See also
+
+- [How to create, edit, move, or delete pages](/en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting)
+- [What we write](/en-US/docs/MDN/Writing_guidelines/What_we_write)
+- [Experimental, deprecated, and obsolete](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete)
+- [Banners and notices](/en-US/docs/MDN/Writing_guidelines/Page_structures/Banners_and_notices)

files/en-us/mdn/writing_guidelines/howto/sunsetting_content/sunset_content/index.md

@@ -0,0 +1,38 @@
+---
+title: Sunset content
+slug: MDN/Writing_guidelines/Howto/Sunsetting_content/Sunset_content
+page-type: mdn-writing-guide
+sidebar: mdnsidebar
+---
+
+This page lists sections of MDN Web Docs that have been sunset. Each entry includes a link to the archived content in the [MDN Museum repository](https://github.com/mdn/museum) and to the GitHub issue or discussion where the sunsetting decision was made.
+
+For details on how sunsetting works, see the [Sunsetting content](/en-US/docs/MDN/Writing_guidelines/Howto/Sunsetting_content) guide.
+
+## Sections
+
+### Canvas Raycaster
+
+- **Sunset:** June 2022
+- **Archived content:** [canvas-raycaster](https://github.com/mdn/museum/tree/main/canvas-raycaster)
+- **Discussion:** [Move canvas-raycaster into mdn/museum](https://github.com/mdn/mdn/issues/193)
+
+A Canvas API raycaster demo and its accompanying documentation page. The content was moved to the museum as part of repository maintenance work.
+
+### WebVR
+
+- **Sunset:** September 2022
+- **Archived content:** [webvr](https://github.com/mdn/museum/tree/main/webvr)
+- **Discussion:** [import webvr tests](https://github.com/mdn/museum/pull/6)
+
+A collection of WebVR API test examples, including basic display info, stage parameters, raw WebGL, VR controller demos, and an A-Frame demo. The WebVR API was deprecated in favor of the [WebXR Device API](/en-US/docs/Web/API/WebXR_Device_API).
+
+<!--
+### Section name
+
+- **Sunset:** MONTH YEAR
+- **Archived content:** [Section name](https://github.com/mdn/museum/tree/main/section_name/)
+- **Discussion:** [Discussion title](https://github.com/orgs/mdn/discussions/XXXX)
+
+Brief description of what the section covered and why it was sunset.
+-->

files/en-us/mdn/writing_guidelines/index.md

@@ -27,6 +27,9 @@ MDN Web Docs is an open-source project. The sections outlined below describe our
     - [How to create, move, and delete pages](/en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting)
       - : This section explains how we create, move, or delete a page on MDN Web Docs. It also explains how we redirect a page when moving or deleting the page.
 
+    - [How to sunset a section of content](/en-US/docs/MDN/Writing_guidelines/Howto/Sunsetting_content)
+      - : This section explains the process for retiring entire sections of MDN Web Docs content in a planned and transparent way, including decision-making, notice periods, archival, and removal.
+
     - [How to use markdown](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN)
       - : The markdown format we use derives from [GitHub flavored markdown (GFM)](https://github.github.com/gfm/). This section is a guide to the markdown we use on MDN Web Docs, including formats for specific in-page components, such as notes and definition lists.
 

files/en-us/mdn/writing_guidelines/what_we_write/index.md

@@ -109,7 +109,7 @@ The following examples describe situations when pages/content might be deleted:
 - Articles contain content that is inappropriate for MDN Web Docs.
 - Sections of MDN Web Docs are not focused on open web technologies and are a maintenance burden.
 
-For more information on _how_ to delete documents, please see the [Creating, moving and deleting pages](/en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting) guide.
+For more information on _how_ to delete individual documents, please see the [Creating, moving and deleting pages](/en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting) guide. If you want to delete an entire section of content, consult the [Sunsetting content](/en-US/docs/MDN/Writing_guidelines/Howto/Sunsetting_content) guide.
 
 ## Types of documents allowed on MDN Web Docs