From bddcd590f0c3aa18e7ea60dbe3a783922cfa9ef4 Mon Sep 17 00:00:00 2001
From: "Daniel D. Beck" <dbeck@mozilla.com>
Date: Thu, 3 Feb 2022 18:06:43 +0000
Subject: [PATCH] Migrate some README sections to contributor site (#12534)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* meta docs: move "can I copy content…" to legacy

* meta docs: move deployment time question to legacy section

* meta docs: remove placeholder on legacy section index page

* meta docs: link from README to meta docs

* meta docs: move external content to legacy section

* meta docs: move archiving to legacy section

* meta docs: move adding code examples to legacy section

* meta docs: use title/linkTitle instead of title/description

* meta docs: move compat tables to legacy docs

* Fix README line length

* Undo prettier formatting to the whole file

* Fix line length for real this time
---
 README.md                                     | 150 +-----------------
 meta/content/en/legacy/_index.md              |   6 +-
 meta/content/en/legacy/archiving.md           |  39 +++++
 meta/content/en/legacy/code-examples.md       |  31 ++++
 meta/content/en/legacy/compat-tables.md       |  16 ++
 meta/content/en/legacy/deployment-timeline.md |  20 +++
 meta/content/en/legacy/external-content.md    |  25 +++
 meta/content/en/legacy/reuse.md               |  32 ++++
 8 files changed, 168 insertions(+), 151 deletions(-)
 create mode 100644 meta/content/en/legacy/archiving.md
 create mode 100644 meta/content/en/legacy/code-examples.md
 create mode 100644 meta/content/en/legacy/compat-tables.md
 create mode 100644 meta/content/en/legacy/deployment-timeline.md
 create mode 100644 meta/content/en/legacy/external-content.md
 create mode 100644 meta/content/en/legacy/reuse.md

diff --git a/README.md b/README.md
index 072f73e920d2d76..46eeff577d97bcc 100644
--- a/README.md
+++ b/README.md
@@ -638,149 +638,7 @@ For example:
 yarn filecheck files/en-us/web/css/my-cool-image.png --save-compression
 ```
 
-### Updating a browser compatibility table
-
-The browser compatibility table shown near the bottom of many of the
-MDN document pages, for example on
-[the JavaScript Array page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#Browser_compatibility),
-is generated from the `npm` package created from the <https://github.com/mdn/browser-compat-data>
-repository. If you'd like to make or suggest a change to the content of
-the browser compatibility table on any given MDN document page, you can either
-use the `Report problems with this data on GitHub` link in the upper-right
-corner of the table on the page itself to create an issue, or go to
-<https://github.com/mdn/browser-compat-data> and
-[read more to learn how to contribute](https://github.com/mdn/browser-compat-data/blob/master/docs/contributing.md).
-
-### Adding code examples
-
-There are a lot of code examples on MDN, and you'll probably want to add
-some as you contribute content to the project. There are four types of
-code example used on MDN:
-
-- [Static examples](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Static_examples)
-  — plain code blocks, possibly with a screenshot to statically show the
-  result of such code if it were to be run.
-- [Traditional MDN "live samples"](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Traditional_live_samples)
-  — A macro that takes plain code blocks, dynamically puts
-  them into a document inside an `<iframe>` element, and embeds it into the
-  page to show the code running live.
-- [GitHub "live samples"](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#GitHub_live_samples)
-  — A macro that takes a document in a GitHub repo inside the [mdn organization](https://github.com/mdn),
-  puts it inside an `<iframe>` element, and embeds
-  it into the page to show the code running live.
-- [Interactive examples](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Interactive_examples)
-  — Our system for creating live interactive examples that show the
-  code running live but also allow you to change code on the fly to see what
-  the effect is.
-
-For a complete description of this topic, see
-[the MDN code examples page](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples).
-
-Also make sure that your code examples follow the
-[MDN code example guidelines](https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Code_guidelines).
-
-### Archiving and unarchiving pages
-
-Pages with the banner "This is an archived page. It's not actively maintained."
-at the top are archived pages — they are archived because either they are
-obsolete or out-of-date, or they are not in scope for MDN contributors to
-actively work on.
-
-If you find a page that is marked archived and you think it shouldn't be,
-you can follow the below steps to unarchive it:
-
-- Submit an issue to check why the page is archived and if it should be
-  unarchived.
-- Find the source code location of the archived page. Archived pages live in
-  the [Archived content](https://github.com/mdn/archived-content/) repo,
-  the structure of which is the same as this repo (except that there are
-  also locale directories present other than `en-US`). As an example:
-  - Take the archived [Mobile developer challenge](https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Mobile_developer_challenge)
-    page, which is at the URL `https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Mobile_developer_challenge`.
-  - This page's source code is at [https://github.com/mdn/archived-content/blob/main/files/en-us/mozilla/mobile/mobile_developer_challenge/index.html](https://github.com/mdn/archived-content/blob/main/files/en-us/mozilla/mobile/mobile_developer_challenge/index.html).
-- To unarchive the page, you need to open a pull request to move the page's
-directory into the appropriate place inside this repo, and update the
-page's meta data (like `slug`) if needed.
-
-> **Note:** To archive a non-archived page, you need to follow the
-above procedure, but move the page in question the opposite way between repos.
-When removing the page from MDN, remember to use the [delete command](#deleting-a-document).
-
-**Note:** You can have an archived page with non-archived pages below it in the
-hierarchy, and vice-versa. To achieve this you need to have the same directory
-structure in both the `content` and `archive-content` repos. Whether a page
-is non-archived or archived depends on which repo its `index.html` file is
-in. As an example, compare the [archived-content mozilla directory](https://github.com/mdn/archived-content/tree/main/files/en-us/mozilla)
-with the [content mozilla directory](https://github.com/mdn/content/tree/main/files/en-us/mozilla).
-Both locations represent the same directory structure, but the
-`index.html` file appears in the latter, therefore the page is not archived.
-
-### Making a change that depends on external content
-
-Some MDN content is created from external data files or repositories using KS macros.
-Generally you should create a PR to first update the external content before
-updating the associated MDN pages.
-
-Relevant external content includes (non-exhaustively):
-
-- [GroupData.json](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json):
-Data definition of
-[Sidebars](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Sidebars)
-used by `{{APIRef}}` macro.
-- [https://github.com/mdn/interactive-examples](https://github.com/mdn/interactive-examples):
-Source code repo for interactive examples inserted using the
-`{{EmbedInteractiveExample}}` macro.
-- [https://github.com/mdn/learning-area](https://github.com/mdn/learning-area):
-Source code repo for examples referenced in the
-[Learning Area](https://developer.mozilla.org/en-US/docs/Learn)
-- [JSON structured data](https://developer.mozilla.org/en-US/docs/MDN/Guidelines/JSON_Structured_Data)
-provides more information about JSON data used to define inheritance diagrams
-(`{{InheritanceDiagram}}` macro), specification tables, etc.
-
-## Frequently asked questions (FAQ)
-
-### When will my change show up on the production MDN site?
-
-After your pull request is merged, it may take up to 48 hours before the
-change goes live on the production <https://developer.mozilla.org/> site,
-but it will usually be quicker.
-
-- The complete build runs every 24h at around 7PM US/Eastern time, and is
-  then deployed.
-- Once deployment has occurred, it can take up to 24 hours for the
-  associated CDN caches to replace their previously-cached content with
-  the updates.
-
-You can use <https://whatsdeployed.io/s/DLi/mdn/content> to see if your change
-has been deployed to the production site.
-And use <https://whatsdeployed.io/s/16d/mdn/translated-content> for changes
-to the <https://github.com/mdn/translated-content> repo.
-
-### Can I copy content from other sources to put on MDN?
-
-In general, we do not approve of copying content from other sources and putting
-it on MDN. MDN should be made up of original content wherever possible. If we
-receive a pull request and discover that it contains plagiarized content,
-we will close it and request that the submitter resubmit the change with
-the content rewritten into their own words.
-
-If someone wants to donate an article to MDN that they previously published on
-their blog or it makes sense to copy a complex reference sheet to MDN there may
-be justification for republishing it. In these cases you should discuss your
-plan with the MDN team first:
-
-1. Include a comment on the relevant repo issue that explains your intention — say
-what you would like to copy (include the URL) and explain why you think this
-is appropriate.
-1. If the content is published under a closed license:
-   - If you hold the rights to the content, state this, and say that you are
-happy to republish it on MDN.
-   - If you do not hold the rights to the content, include the author/publisher
-   on the issue if possible, or include details of how they could be contacted
-   so we can ask them for permission to republish the content.
-1. If the content is published under an open license, say what it is, and link
-to the license so we can check whether it is compatible with [MDN's license](https://developer.mozilla.org/en-US/docs/MDN/About#using_mdn_web_docs_content).
-1. @-mention chrisdavidmills on the issue, so he can review the request.
-
-Be warned that unless there is a good reason to republish the content, we will
-probably say "no". The MDN writing team's decision is final.
+## Learn more
+
+You can learn more about contributing to MDN on
+[the MDN Web Docs for Contributors site](https://mdn-contributor-docs.mozilla.org/).
diff --git a/meta/content/en/legacy/_index.md b/meta/content/en/legacy/_index.md
index 714df78328f4797..a8028acdc26a1a5 100644
--- a/meta/content/en/legacy/_index.md
+++ b/meta/content/en/legacy/_index.md
@@ -2,9 +2,5 @@
 title: "Legacy documentation"
 weight: 1000
 description: >
-  This page needs a description.
+  Unedited contributor documentation migrated from GitHub and MDN itself.
 ---
-
-{{% pageinfo %}}
-This is a placeholder page.
-{{% /pageinfo %}}
diff --git a/meta/content/en/legacy/archiving.md b/meta/content/en/legacy/archiving.md
new file mode 100644
index 000000000000000..ed9c2cb1b42b5ac
--- /dev/null
+++ b/meta/content/en/legacy/archiving.md
@@ -0,0 +1,39 @@
+---
+title: "Archiving and unarchiving pages"
+linkTitle: "Archiving"
+weight: 4
+---
+
+Pages with the banner "This is an archived page. It's not actively maintained."
+at the top are archived pages — they are archived because either they are
+obsolete or out-of-date, or they are not in scope for MDN contributors to
+actively work on.
+
+If you find a page that is marked archived and you think it shouldn't be,
+you can follow the below steps to unarchive it:
+
+- Submit an issue to check why the page is archived and if it should be
+  unarchived.
+- Find the source code location of the archived page. Archived pages live in
+  the [Archived content](https://github.com/mdn/archived-content/) repo,
+  the structure of which is the same as this repo (except that there are
+  also locale directories present other than `en-US`). As an example:
+  - Take the archived [Mobile developer challenge](https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Mobile_developer_challenge)
+    page, which is at the URL `https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Mobile_developer_challenge`.
+  - This page's source code is at [https://github.com/mdn/archived-content/blob/main/files/en-us/mozilla/mobile/mobile_developer_challenge/index.html](https://github.com/mdn/archived-content/blob/main/files/en-us/mozilla/mobile/mobile_developer_challenge/index.html).
+- To unarchive the page, you need to open a pull request to move the page's
+  directory into the appropriate place inside this repo, and update the
+  page's meta data (like `slug`) if needed.
+
+> **Note:** To archive a non-archived page, you need to follow the
+> above procedure, but move the page in question the opposite way between repos.
+> When removing the page from MDN, remember to use the [delete command](#deleting-a-document).
+
+**Note:** You can have an archived page with non-archived pages below it in the
+hierarchy, and vice-versa. To achieve this you need to have the same directory
+structure in both the `content` and `archive-content` repos. Whether a page
+is non-archived or archived depends on which repo its `index.html` file is
+in. As an example, compare the [archived-content mozilla directory](https://github.com/mdn/archived-content/tree/main/files/en-us/mozilla)
+with the [content mozilla directory](https://github.com/mdn/content/tree/main/files/en-us/mozilla).
+Both locations represent the same directory structure, but the
+`index.html` file appears in the latter, therefore the page is not archived.
diff --git a/meta/content/en/legacy/code-examples.md b/meta/content/en/legacy/code-examples.md
new file mode 100644
index 000000000000000..4cb3ad5eb1a50cd
--- /dev/null
+++ b/meta/content/en/legacy/code-examples.md
@@ -0,0 +1,31 @@
+---
+title: "Adding code examples"
+linkTitle: "Code examples"
+weight: 4
+---
+
+There are a lot of code examples on MDN, and you'll probably want to add
+some as you contribute content to the project. There are four types of
+code example used on MDN:
+
+- [Static examples](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Static_examples)
+  — plain code blocks, possibly with a screenshot to statically show the
+  result of such code if it were to be run.
+- [Traditional MDN "live samples"](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Traditional_live_samples)
+  — A macro that takes plain code blocks, dynamically puts
+  them into a document inside an `<iframe>` element, and embeds it into the
+  page to show the code running live.
+- [GitHub "live samples"](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#GitHub_live_samples)
+  — A macro that takes a document in a GitHub repo inside the [mdn organization](https://github.com/mdn),
+  puts it inside an `<iframe>` element, and embeds
+  it into the page to show the code running live.
+- [Interactive examples](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Interactive_examples)
+  — Our system for creating live interactive examples that show the
+  code running live but also allow you to change code on the fly to see what
+  the effect is.
+
+For a complete description of this topic, see
+[the MDN code examples page](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples).
+
+Also make sure that your code examples follow the
+[MDN code example guidelines](https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Code_guidelines).
diff --git a/meta/content/en/legacy/compat-tables.md b/meta/content/en/legacy/compat-tables.md
new file mode 100644
index 000000000000000..84dc67176901a10
--- /dev/null
+++ b/meta/content/en/legacy/compat-tables.md
@@ -0,0 +1,16 @@
+---
+title: "Updating a browser compatibility table"
+linkTitle: "Compatibility tables"
+weight: 4
+---
+
+The browser compatibility table shown near the bottom of many of the
+MDN document pages, for example on
+[the JavaScript Array page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#Browser_compatibility),
+is generated from the `npm` package created from the <https://github.com/mdn/browser-compat-data>
+repository. If you'd like to make or suggest a change to the content of
+the browser compatibility table on any given MDN document page, you can either
+use the `Report problems with this data on GitHub` link in the upper-right
+corner of the table on the page itself to create an issue, or go to
+<https://github.com/mdn/browser-compat-data> and
+[read more to learn how to contribute](https://github.com/mdn/browser-compat-data/blob/master/docs/contributing.md).
diff --git a/meta/content/en/legacy/deployment-timeline.md b/meta/content/en/legacy/deployment-timeline.md
new file mode 100644
index 000000000000000..96997d5c49f1c4d
--- /dev/null
+++ b/meta/content/en/legacy/deployment-timeline.md
@@ -0,0 +1,20 @@
+---
+title: "When will my change show up on the production MDN site?"
+linkTitle: "Deployment timeline"
+weight: 4
+---
+
+After your pull request is merged, it may take up to 48 hours before the
+change goes live on the production <https://developer.mozilla.org/> site,
+but it will usually be quicker.
+
+- The complete build runs every 24h at around 7PM US/Eastern time, and is
+  then deployed.
+- Once deployment has occurred, it can take up to 24 hours for the
+  associated CDN caches to replace their previously-cached content with
+  the updates.
+
+You can use <https://whatsdeployed.io/s/DLi/mdn/content> to see if your change
+has been deployed to the production site.
+And use <https://whatsdeployed.io/s/16d/mdn/translated-content> for changes
+to the <https://github.com/mdn/translated-content> repo.
diff --git a/meta/content/en/legacy/external-content.md b/meta/content/en/legacy/external-content.md
new file mode 100644
index 000000000000000..c1e32a7fb577115
--- /dev/null
+++ b/meta/content/en/legacy/external-content.md
@@ -0,0 +1,25 @@
+---
+title: "Making a change that depends on external content"
+linkTitle: "External content"
+weight: 4
+---
+
+Some MDN content is created from external data files or repositories using KS macros.
+Generally you should create a PR to first update the external content before
+updating the associated MDN pages.
+
+Relevant external content includes (non-exhaustively):
+
+- [GroupData.json](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json):
+  Data definition of
+  [Sidebars](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Sidebars)
+  used by `{{APIRef}}` macro.
+- [https://github.com/mdn/interactive-examples](https://github.com/mdn/interactive-examples):
+  Source code repo for interactive examples inserted using the
+  `{{EmbedInteractiveExample}}` macro.
+- [https://github.com/mdn/learning-area](https://github.com/mdn/learning-area):
+  Source code repo for examples referenced in the
+  [Learning Area](https://developer.mozilla.org/en-US/docs/Learn)
+- [JSON structured data](https://developer.mozilla.org/en-US/docs/MDN/Guidelines/JSON_Structured_Data)
+  provides more information about JSON data used to define inheritance diagrams
+  (`{{InheritanceDiagram}}` macro), specification tables, etc.
diff --git a/meta/content/en/legacy/reuse.md b/meta/content/en/legacy/reuse.md
new file mode 100644
index 000000000000000..4615422b536193b
--- /dev/null
+++ b/meta/content/en/legacy/reuse.md
@@ -0,0 +1,32 @@
+---
+title: "Can I copy content from other sources to put on MDN?"
+linkTitle: "Reuse policy"
+weight: 4
+---
+
+In general, we do not approve of copying content from other sources and putting
+it on MDN. MDN should be made up of original content wherever possible. If we
+receive a pull request and discover that it contains plagiarized content,
+we will close it and request that the submitter resubmit the change with
+the content rewritten into their own words.
+
+If someone wants to donate an article to MDN that they previously published on
+their blog or it makes sense to copy a complex reference sheet to MDN there may
+be justification for republishing it. In these cases you should discuss your
+plan with the MDN team first:
+
+1. Include a comment on the relevant repo issue that explains your intention — say
+   what you would like to copy (include the URL) and explain why you think this
+   is appropriate.
+1. If the content is published under a closed license:
+   - If you hold the rights to the content, state this, and say that you are
+     happy to republish it on MDN.
+   - If you do not hold the rights to the content, include the author/publisher
+     on the issue if possible, or include details of how they could be contacted
+     so we can ask them for permission to republish the content.
+1. If the content is published under an open license, say what it is, and link
+   to the license so we can check whether it is compatible with [MDN's license](https://developer.mozilla.org/en-US/docs/MDN/About#using_mdn_web_docs_content).
+1. @-mention chrisdavidmills on the issue, so he can review the request.
+
+Be warned that unless there is a good reason to republish the content, we will
+probably say "no". The MDN writing team's decision is final.