From a2559eb15893c286368daef9be9372c8ca1d5b81 Mon Sep 17 00:00:00 2001 From: dawei-wang Date: Wed, 24 Jan 2024 08:30:51 -0800 Subject: [PATCH] delete redundant pages from mdn directory (#31878) --- files/en-us/_redirects.txt | 20 ++- files/en-us/_wikihistory.json | 37 ------ .../en-us/mdn/community/mdn_content/index.md | 48 ------- .../mdn/community/mdn_content/issues/index.md | 9 -- .../mdn_content/pull_requests/index.md | 58 -------- files/en-us/mdn/contribute/index.md | 125 ------------------ files/en-us/mdn/contribute/processes/index.md | 11 -- .../workstream_assessment_project/index.md | 124 ----------------- 8 files changed, 13 insertions(+), 419 deletions(-) delete mode 100644 files/en-us/mdn/community/mdn_content/index.md delete mode 100644 files/en-us/mdn/community/mdn_content/issues/index.md delete mode 100644 files/en-us/mdn/community/mdn_content/pull_requests/index.md delete mode 100644 files/en-us/mdn/contribute/index.md delete mode 100644 files/en-us/mdn/contribute/processes/index.md delete mode 100644 files/en-us/mdn/contribute/processes/workstream_assessment_project/index.md diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 0a79542b5b1b436..c44f67224025350 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -5396,11 +5396,15 @@ /en-US/docs/Liberty!_Equality!_Validity! /en-US/docs/Learn/HTML/Introduction_to_HTML/Debugging_HTML /en-US/docs/Link_prefetching_FAQ /en-US/docs/Glossary/Prefetch /en-US/docs/Localization /en-US/docs/Glossary/Localization -/en-US/docs/MDC:How_to_Help /en-US/docs/MDN/Contribute +/en-US/docs/MDC:How_to_Help /en-US/docs/MDN/Community/Contributing /en-US/docs/MDN/About /en-US/docs/MDN/Writing_guidelines -/en-US/docs/MDN/At_ten/Contributing_to_MDN /en-US/docs/MDN/Contribute +/en-US/docs/MDN/At_ten/Contributing_to_MDN /en-US/docs/MDN/Community/Contributing /en-US/docs/MDN/Community/Issues/Issue_triage /en-US/docs/MDN/Community/Issues +/en-US/docs/MDN/Community/MDN_content /en-US/docs/MDN/Community/Contributing +/en-US/docs/MDN/Community/MDN_content/Issues /en-US/docs/MDN/Community/Issues +/en-US/docs/MDN/Community/MDN_content/Pull_requests /en-US/docs/MDN/Community/Pull_requests /en-US/docs/MDN/Community/Users_teams /en-US/docs/MDN/Community/Roles_teams +/en-US/docs/MDN/Contribute /en-US/docs/MDN/Community/Contributing /en-US/docs/MDN/Contribute/Changelog /en-US/docs/MDN/Changelog /en-US/docs/MDN/Contribute/Code_sample_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide /en-US/docs/MDN/Contribute/Content /en-US/docs/MDN/Writing_guidelines @@ -5416,9 +5420,9 @@ /en-US/docs/MDN/Contribute/Creating_and_editing_pages /en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting /en-US/docs/MDN/Contribute/Does_this_belong /en-US/docs/MDN/Writing_guidelines/What_we_write /en-US/docs/MDN/Contribute/Editor/Live_samples /en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples -/en-US/docs/MDN/Contribute/FAQ /en-US/docs/MDN/Contribute +/en-US/docs/MDN/Contribute/FAQ /en-US/docs/MDN/Community/Contributing /en-US/docs/MDN/Contribute/Feedback /en-US/docs/MDN/Community -/en-US/docs/MDN/Contribute/Fixing_MDN_content_bugs /en-US/docs/MDN/Community/MDN_content +/en-US/docs/MDN/Contribute/Fixing_MDN_content_bugs /en-US/docs/MDN/Community/Contributing /en-US/docs/MDN/Contribute/Getting_started /en-US/docs/MDN/Community/Contributing/Getting_started /en-US/docs/MDN/Contribute/GitHub_beginners /en-US/docs/MDN/Community/Contributing/Getting_started /en-US/docs/MDN/Contribute/GitHub_best_practices /en-US/docs/MDN/Community/Issues @@ -5450,7 +5454,7 @@ /en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide /en-US/docs/MDN/Writing_guidelines/Writing_style_guide /en-US/docs/MDN/Contribute/Help_beginners /en-US/docs/MDN/Community/Learn_forum /en-US/docs/MDN/Contribute/How_to_document_a_CSS_property /en-US/docs/MDN/Writing_guidelines/Howto/Document_a_CSS_property -/en-US/docs/MDN/Contribute/Howto /en-US/docs/MDN/Contribute +/en-US/docs/MDN/Contribute/Howto /en-US/docs/MDN/Community/Contributing /en-US/docs/MDN/Contribute/Howto/Add_or_update_browser_compatibility_data https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md /en-US/docs/MDN/Contribute/Howto/Compatibility_tables /en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables /en-US/docs/MDN/Contribute/Howto/Convert_code_samples_to_be_live /en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples @@ -5473,11 +5477,13 @@ /en-US/docs/MDN/Contribute/Localize /en-US/docs/MDN/Community/Contributing/Translated_content /en-US/docs/MDN/Contribute/Markdown_in_MDN /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Contribute/Open_source_etiquette /en-US/docs/MDN/Community/Open_source_etiquette +/en-US/docs/MDN/Contribute/Processes /en-US/docs/MDN/Community/Contributing /en-US/docs/MDN/Contribute/Processes/Content_bug_triage /en-US/docs/MDN/Community/Issues /en-US/docs/MDN/Contribute/Processes/Locating_browser-specific_information https://github.com/mdn/browser-compat-data/blob/main/docs/matching-browser-releases/index.md /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_version https://github.com/mdn/browser-compat-data/blob/main/docs/matching-browser-releases/index.md /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_versiosn https://github.com/mdn/browser-compat-data/blob/main/docs/matching-browser-releases/index.md -/en-US/docs/MDN/Contribute/Processes/Short_surveys /en-US/docs/MDN/Contribute +/en-US/docs/MDN/Contribute/Processes/Short_surveys /en-US/docs/MDN/Community/Contributing +/en-US/docs/MDN/Contribute/Processes/Workstream_assessment_project /en-US/docs/MDN/Community/Contributing /en-US/docs/MDN/Contribute/Sample_app_coding_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide /en-US/docs/MDN/Contribute/Sample_server /en-US/docs/MDN /en-US/docs/MDN/Contribute/Structures /en-US/docs/MDN/Writing_guidelines/Page_structures @@ -5601,7 +5607,7 @@ /en-US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria /en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion /en-US/docs/MDN/Yari https://github.com/mdn/yari/tree/main/docs /en-US/docs/MDN_at_ten /en-US/docs/MDN/At_ten -/en-US/docs/MDN_at_ten/Contributing_to_MDN /en-US/docs/MDN/Contribute +/en-US/docs/MDN_at_ten/Contributing_to_MDN /en-US/docs/MDN/Community/Contributing /en-US/docs/MDN_at_ten/History /en-US/docs/MDN/At_ten/History_of_MDN /en-US/docs/MDN_at_ten/History_of_MDN /en-US/docs/MDN/At_ten/History_of_MDN /en-US/docs/Main_page /en-US/ diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index 4b583f788b7fc0d..1a51406ef60da4b 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -11697,43 +11697,6 @@ "groovecoder" ] }, - "MDN/Contribute": { - "modified": "2020-12-14T09:31:17.213Z", - "contributors": [ - "sourabhramsingh", - "maxTarlov", - "chrisdavidmills", - "aditibasu", - "wbamberg", - "SphinxKnight", - "shwetabhsuman", - "jswisher", - "wdot789", - "fotografi", - "Sheppy", - "vikash111", - "Kerstomaat", - "ertogrul", - "elwakil", - "Thomskii", - "Lasantha", - "jsx", - "saifulislam1", - "adi28galaxyak", - "Volluta", - "Husaria", - "klez", - "pytseng", - "alispivak", - "utente-pc", - "emmanuelodenyire", - "Mars" - ] - }, - "MDN/Contribute/Processes": { - "modified": "2020-09-30T15:17:09.733Z", - "contributors": ["wbamberg", "david_ross", "jswisher", "Sheppy"] - }, "MDN/MDN_Product_Advisory_Board": { "modified": "2019-06-05T12:41:23.682Z", "contributors": [ diff --git a/files/en-us/mdn/community/mdn_content/index.md b/files/en-us/mdn/community/mdn_content/index.md deleted file mode 100644 index cd26f91416f0b89..000000000000000 --- a/files/en-us/mdn/community/mdn_content/index.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Contributing to MDN Web Docs content -slug: MDN/Community/MDN_content -page-type: mdn-community-guide ---- - -{{MDNSidebar}} - -Problems with MDN Web Docs are reported as [content repo issues](https://github.com/mdn/content/issues). This article helps you find the _best_ issues to work on, based on your expertise and how much time you have available, and outlines the main steps to fixing them. - -> **Note:** We get a lot of content bugs — any help you can give in fixing them is very much appreciated! - -## What we need help with - -To help you choose what content issues to work on, we've sorted them using GitHub labels. - -The labels below help you find tasks based on estimated effort to complete the task. - -| Label | Description | -| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| [effort: small](https://github.com/mdn/content/labels/effort%3A%20small) | A task that will probably require little effort, such as fixing a typo, or adding a few sentences of clarification. | -| [effort: medium](https://github.com/mdn/content/labels/effort%3A%20medium) | A task that will probably require non-trivial effort. For example, updating a page to reflect changes to the formal specification. | -| [effort: large](https://github.com/mdn/content/labels/effort%3A%20large) | A task that will probably require significant and large-scale effort, such as writing new guide and reference pages. | - -If you'd prefer to browse your tasks and choose by technology category instead, you can also find content type labels on [issues in the content repository](https://github.com/mdn/content/issues). - -## How you can benefit - -- Fixing MDN content bugs is a great way to learn more about web technologies — as you research a problem and create the required content, you will gain a deeper understanding of the subject, and improve your skills. -- As you get more involved in the MDN community, you'll get to know Mozilla staff and other community members, giving you a valuable network of contacts for getting help with your own issues and increasing your visibility. -- Helping to fix problems is largely its own reward, but it will also serve as a record of your open source contributions, demonstrating your expertise in web technologies and possibly even helping you with your course, or job opportunities. - -## What skills you need - -- You need to be knowledgeable in the topic areas that you choose to help with (e.g. JavaScript, CSS). -- Most of the examples and pages that you will help with are written in English, so you should have a reasonable understanding of the English language. But don't worry if your English is not perfect! Our team is more than happy to help clean up any writing. - -## How to help - -1. First of all, sign up for a [GitHub account](https://github.com/join), if you don't already have one — you'll need this to communicate on the GitHub issues. -2. Next, choose one or more topic areas you'd like to help with. Use the list above to get more information to help you make your selection. If you are not sure what a good choice would be, ask for help in the [MDN Web Docs chat rooms](/en-US/docs/MDN/Community/Communication_channels#chat_rooms). - -After you are set up, you can: - -1. Choose an issue to work on that interests you, and ask us to assign it to you with a comment on the issue. -2. If you need any help when you are working on it, feel free to contact us in the [MDN Web Docs chat rooms](/en-US/docs/MDN/Community/Communication_channels#chat_rooms). -3. Once you've fixed an issue, ask the submitter for a review and, hopefully, they will tell you whether they think more work is required. We will get involved if needed. -4. Once the issue is verified fixed, it can be closed. The person closing the issue can be either the original issue submitter, or an MDN staff member. diff --git a/files/en-us/mdn/community/mdn_content/issues/index.md b/files/en-us/mdn/community/mdn_content/issues/index.md deleted file mode 100644 index 1bbefe37cb01e71..000000000000000 --- a/files/en-us/mdn/community/mdn_content/issues/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Using issues on MDN Web Docs -slug: MDN/Community/MDN_content/Issues -page-type: mdn-community-guide ---- - -{{MDNSidebar}} - -TBD diff --git a/files/en-us/mdn/community/mdn_content/pull_requests/index.md b/files/en-us/mdn/community/mdn_content/pull_requests/index.md deleted file mode 100644 index 3e49accfabdff54..000000000000000 --- a/files/en-us/mdn/community/mdn_content/pull_requests/index.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Pull request etiquette and process for MDN Web Docs -slug: MDN/Community/MDN_content/Pull_requests -page-type: mdn-community-guide ---- - -{{MDNSidebar}} - -## Overall process - -This section describes how contributors make changes on MDN Web Docs and how the changes are reviewed and land on the site. - -### Types of content changes on MDN Web Docs - -Content changes we get on MDN Web Docs are related to a variety of work streams, some of which include: - -- **Day-to-day content improvement work**: This includes documentation of new APIs, new CSS properties, and other significant content additions. This is usually done by MDN Web Docs staff working for Mozilla, Google, Open Web Docs, Samsung, etc., but also sometimes by community volunteers. -- **"Drive-by" fixes**: This includes small updates done to the site to fix typos, grammatical issues, and technical inaccuracies. These issues are usually found by users of MDN Web Docs. -- **Content bug fixes**: These are usually done by volunteers to close issues on mdn/content repo. - -### How content changes are reviewed - -Regardless of how content changes are done, they will be submitted as pull requests on this repo, which requires rapid reviewing and merging to ensure that the site does not get out-of-date. This is managed in the following way: - -1. **Reviewer assignment**: Different MDN staff members and volunteers have been assigned as "topic review owners", meaning that when a pull request related to a particular topic area of the site (e.g. the CSS reference, or the learning area) is opened, it will be assigned to that area's topic review owner(s). This is handled using the CODEOWNERS file, in which particular content directories are assigned to the respective reviewing team. -2. **Review, approval, merge**: Once the review has been done and the pull request has been approved, the assigned reviewer merges the pull request. -3. **Content update on the site**: The site is rebuilt once every 24 hours to ensure that the content does not get too stale. So volunteers can see their changes go live after 24 hours. - -### Things to consider before opening a pull request - -These guidelines apply to anyone opening a PR to make a change on MDN Web Docs. - -- **Open issue or discussion before opening PR**: If your PR would contain any kind of significant complexity (for example, it contains technical changes and isn't just a typo fix, grammatical improvement, or a formatting/structural change), please open an [issue](https://github.com/mdn/content/issues/new/choose) or [discussion](https://github.com/mdn/mdn-community) to describe why you're making the change, how the change would improve the content, and anything else we need to know about the change. Specifically for content suggestions or feature proposals, we have a [well documented](/en-US/docs/MDN/Community/Issues/Content_suggestions_feature_proposals) process to follow. -- **Keep the PR short (1 issue per PR)**: Each PR should contain a single logical change or a related set of changes that make sense to submit together. If a PR becomes too large or contains too many unrelated changes, it becomes too difficult to review, and may begin to look suspicious (it is easier to hide malicious changes in a large PR). In such cases, the reviewer has the right to close your PR, and ask that you submit a separate PR for each logical set of changes that belong together. It is also good practice to reference the relevant issue in your PR description using [GitHub's special syntax](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). This helps maintenance as GitHub will automatically close linked issues once the PR is merged. -- **PR to update grammar**: PRs should not contain large amounts of grammar updates. Seemingly insignificant changes can change the meaning of technical content, so these need a careful review. Keep in mind that MDN Web Docs contains technical documentation; you should not report basic improvements in the grammar but only cases where the grammar is clearly incorrect. -- **PR to update a demo repository**: For PRs that update API usage, there needs to be an accompanying PR on the mdn/content repository to update the corresponding relevant documentation. Such a PR can be rejected if there is no corresponding content PR. -- **Only enable auto-merge for approved PRs**: It is not a recommended practice to select the "Enable auto-merge (squash)" checkbox on your PRs that are waiting to be reviewed or approved. - -### Guidelines for after submitting a pull request - -We have general guidelines for what to do and expect after a PR has been opened. Please [refer to these guidelines](/en-US/docs/MDN/Community/Pull_requests). - -### Guidelines for pull request review assignments - -These guidelines apply to anyone who is tasked with reviewing MDN content PRs. - -#### If you are the assigned reviewer - -- **Add a starting comment**: Add a comment as soon as possible that you are aware of the PR and will start the review soon. This is an important step to avoid someone else reviewing the PR at the same time as you and so that others know it's on your radar for review. -- **Ask for information from the PR author**: You can request more information to help with your review if the PR author has not explained why they are making this change. Ideally, they should reference an issue that they're trying to fix in this PR. -- **Ask for help**: If you're open to receiving or want technical help with the review, add the `review-help-needed` label. - -If you don't understand a content change that you've been selected to review or feel that it is too large and complex for you to deal with, don't panic! Feel free to reach out to someone else to ask for help, like a colleague or someone else in your group of topic review owners (if you know who they are). If you are not sure who to approach for help, then ping our `@mdn/core-yari-content` group to ask for help. - -Related to the above point, it is rare that you'll be required to review a large, complex content change with no warning, like a complete page rewrite, or the addition of several new reference pages or tutorials. Usually such changes are done as part of specific work streams where the content has been approved for addition and reviewer(s) have been assigned already. In such cases, the PR should be linked to an issue that explains all these details. If you are not sure, ask the PR author if they need a review of the content, and where the rationale behind the change is explained. Ping our team in the [MDN Web Docs chat rooms](/en-US/docs/MDN/Community/Communication_channels#chat_rooms) to ask for help if you are still not sure or if you think the content is suspicious. - -- **Close PR with unrelated changes**: You have the right to close a PR if it is too complex and/or contains multiple unrelated changes and ask the PR author to submit their changes in smaller atomic chunks. -- **Ask for load balancing help**: If your plate is full at the moment and you don't think you will be able to complete the review in a timely manner, copy the `@mdn/core-yari-content` team and ask if someone else can take up the review. diff --git a/files/en-us/mdn/contribute/index.md b/files/en-us/mdn/contribute/index.md deleted file mode 100644 index ce4a170266f02cd..000000000000000 --- a/files/en-us/mdn/contribute/index.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Contributing to MDN -slug: MDN/Contribute -page-type: landing-page ---- - -{{MDNSidebar}} - -MDN Web Docs needs your help! We have a large number of typos to fix, examples to write, bugs to fix, people to talk to, and more, and the number is growing as more people start using the site. This page outlines what you can do to help. - -> **Note:** If you haven't contributed to MDN previously, the [Getting Started](/en-US/docs/MDN/Community/Contributing/Getting_started) guide explains the process in four simple steps. Good news, you're already on step 2: "Picking a task to complete."! - -## What can I do to help? - -There are multiple avenues you can take to contribute to MDN depending on your skill set and interests. Along with each task we provide a short description and an approximate time that each type of task typically takes. - -If you are not sure what to do, you are always welcome to [ask for help](/en-US/docs/MDN/Community/Communication_channels). - -### Primary contribution types - -The links in this section lead to detailed guides explaining how to do a particular contribution task that we are most interested in getting community help with, either because they are a critical function, and/or because they have a large backlog associated with them. Please consider helping out with these tasks before you consider contributing in other ways. - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Contribution Categories
TasksDescriptionSkill set required
- Fixing MDN content bugs - - Our content repo is where people submit issues to report problems found with MDN docs. - We get a lot of content bugs, and any help you can give in fixing them would be much appreciated. - -
    -
  • - Knowledge of the web technologies you choose to help with (e.g. JavaScript, CSS). -
    • -
  • - A reasonable understanding of the English language (don't worry if your English is not perfect; we can help you with it). -
    • -
-
- Reviewing MDN edits - - People submit pull requests on our content repo all the time to update MDN content, and we need help reviewing them. - Head over to our REVIEWING.md page to find out how the reviewing process works, and how you can get involved. - -
    -
  • - Knowledge of the web technologies you choose to help with (e.g. JavaScript, CSS). -
    • -
  • - A reasonable understanding of the English language (don't worry if your English is not perfect; we can help you with it). -
    • -
-
- Help beginners to learn on MDN - - Our Learn web development pages get over a million views per month and has an active community where people ask for guidance. - We'd love some help with answering technical questions and growing our learning community. - -
    -
  • - Knowledge of the web technologies you choose to help with (e.g. JavaScript, CSS). -
    • -
  • - Enthusiasm for explaining technical topics and helping beginners learn to code. -
    • -
  • - Reasonable proficiency with the English language; it really doesn't need to be perfect. -
    • -
-
- -We will add more tasks here as time goes on. - -### Other task types - -If our main priorities listed above don't interest you, you can find a number of other, more general task types to get involved with below, split up by skill set. - -If you are more interested in words, you could do the following: - -- [Update an existing article with new information](/en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting#editing_an_existing_page) (5 minutes-1 hour) -- [Write a new entry in the Glossary](/en-US/docs/MDN/Writing_guidelines/Howto/Write_a_new_entry_in_the_glossary) (15 minutes-1 hour) - -If you are more interested in code, you could try your hand at the following: - -- [Convert code samples to be "live"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples) (30 minutes) -- [Send a code patch to the Yari codebase](https://github.com/mdn/yari) (1 hour) -- [Write an interactive example](https://github.com/mdn/interactive-examples/blob/main/CONTRIBUTING.md) (1 hour) - -If you are interested in words _and_ code, you could try your hand at the following: - -- [Write or update an API reference](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_api_reference) (30 minutes to 2 hours, or more) -- [Write a new article on a topic you are familiar with](https://github.com/mdn/content#adding-a-new-document) (1 hour or more) -- [Add or update browser compatibility data on a reference page](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables) (30 minutes to 1 hour) - -> **Note:** If you have found something that is incorrect on MDN but you're not sure how to fix it, you can report problems by [filing a documentation issue](https://github.com/mdn/content/issues/new/choose). Please give the issue a descriptive title. (It's not helpful to say "Dead link" without saying where you found the link). - -## Other useful pages - -{{LandingPageListSubPages}} diff --git a/files/en-us/mdn/contribute/processes/index.md b/files/en-us/mdn/contribute/processes/index.md deleted file mode 100644 index b37ea9b5f26c525..000000000000000 --- a/files/en-us/mdn/contribute/processes/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Documentation processes -slug: MDN/Contribute/Processes -page-type: landing-page ---- - -{{MDNSidebar}} - -The MDN documentation project is enormous; there are a vast number of technologies we cover through the assistance of hundreds of contributors from across the world. To help us bring order to chaos, we have standard processes to follow when working on specific documentation-related tasks. Here you'll find guides to those processes. - -{{LandingPageListSubPages}} diff --git a/files/en-us/mdn/contribute/processes/workstream_assessment_project/index.md b/files/en-us/mdn/contribute/processes/workstream_assessment_project/index.md deleted file mode 100644 index 8578bc2e70c4d8c..000000000000000 --- a/files/en-us/mdn/contribute/processes/workstream_assessment_project/index.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: MDN Workstream assessment and project setup process -slug: MDN/Contribute/Processes/Workstream_assessment_project -page-type: guide ---- - -{{MDNSidebar}} - -Workstreams are larger, more involved MDN projects that are designed to be done by multiple people (across organizations) and require planning/process. They start life as content opportunities. - -## Content opportunity assessment - -Once per month we have a content opportunity assessment meeting. During this meeting we assess new opportunities, and record the results in the [content opportunities spreadsheet](https://docs.google.com/spreadsheets/d/13YYX5rRu4ATbo1Yl7rXHF9rbgXGBSLisguzo-cB8Fno/edit#gid=0). Near the end of each quarter, we have a further meeting to decide which of the opportunities assessed this quarter will be added to the roadmap for the next quarter. - -The process looks like this: - -1. Opportunities are initially submitted as issues to the [mdn/content](https://github.com/mdn/content) or [openwebdocs/project](https://github.com/openwebdocs/project) repositories. These issues are given a preliminary quick assessment by a core team member to assess suitability. -2. If an idea is deemed suitable, the issue submitter is asked to fill in a full RFC document to be assessed. This is currently done by updating the existing issue's description to use the format seen at [OWD project: Making MDN syntax boxes beginner friendly](https://github.com/openwebdocs/project/issues/26). - - - Note that in the "Priority assessment" table, each opportunity needs to be assessed against our [prioritization criteria](https://github.com/openwebdocs/project/blob/main/steering-committee/prioritization-criteria.md). - - For each criterion, give the project a description as well as a rough score of none/small/medium/large. - -3. Each month, we hold the opportunity assessment meeting to assess new opportunities, and record the results in the [content opportunities spreadsheet](https://docs.google.com/spreadsheets/d/13YYX5rRu4ATbo1Yl7rXHF9rbgXGBSLisguzo-cB8Fno/edit#gid=0). To be discussed in a meeting, each assessment needs an RFC submitted, to act as the basis for our discussion. -4. At the end of each opportunity assessment meeting, we stack rank the ideas: - - - We vote on the priority order for the ideas discussed by writing a simple number order in the meeting chat. For example if three opportunities were discussed and you thought that 2 was the most important, followed by 1, followed by 3, you'd write "2,1,3". - - We tally the votes and create a priority order for that meeting's opportunities. - - We then decide how those opportunities fit into the overall stack rank, by discussing where we think they'd fit. - -5. In the middle of the last month in each quarter, we have a meeting to look at the submitted opportunities, and decide which ones should be put on the MDN content roadmap for the next quarter. We present this proposal to the [Open Web Docs (OWD)](https://github.com/openwebdocs) editorial steering committee to get signed off. Each assessed opportunity is given a decision word — "roadmap", "park" or "decline": - - - Roadmap — we are going ahead with this by putting it on the roadmap. - - Park — we are not going forward with this yet, but will consider it in the future. - - Decline — we are not going forward with this opportunity. - -6. Projects that are added to the roadmap are moved onto the project setup stage. At this stage, each one needs a project lead assigned that will make sure the work happens. - -> **Note:** If there is any disagreement about any of the given scores or decisions during the opportunity assessment meetings, the chair of the meeting will listen to opposing views for a maximum of one minute per view, then make a final decision on the matter. The chair's decision is final. - -## MDN project setup - -Workstreams that are signed off by the OWD editorial steering committee will follow the process outlined in this section and the next one. This first section details with the setup required for each workstream, and the second one looks at the process to follow when actually working on a project. - -### Overall project summary issue - -Each workstream needs an overall project summary issue, created on the [mdn/content](https://github.com/mdn/content) repo, to act as a focal point and summary for the project work. - -This should include: - -- A link to the RFC created for the workstream during the assessment process, so people can find further background information on the project if they need it. -- Links to the spec or specs for the features being documented, as appropriate. -- A list of the people involved in the project. Say what they are doing on it, and include their GitHub handles so that people can contact them if needed. -- What are the success criteria for this project? Obviously we want to do all the listed tasks, but what is the effect of that going to be? A certain monthly page view figure for the new docs? Reduction in bugs received about a certain topic? -- Other links that are useful to this project. -- A list of what content and engineering work is required to complete this project. Eventually this should be a list of links to issues that define this work, as described in the [Individual work issues](#individual_work_issues) section. - -### Add to shared project roadmap - -Each workstream should be added to the shared project roadmap (which currently lives in the [High-level MDN schedule](https://docs.google.com/spreadsheets/d/1dMK17xXgPQxnfsMZedi-uf5EVdJcagk3BhuxJlxC6l8/edit#gid=0) spreadsheet). This is a really simple view of what work is being done and when. Each project entry should span across the months it is being done in, and link to the [overall project summary issue](#overall_project_summary_issue) for more information if required. - -Add your workstream/project to the spreadsheet, or ask someone else to do so if you don't have editing access. - -### Individual work issues - -The next step is to create individual GitHub issues for each bit of work listed in the overall project summary, and link to those issues from there. Each issue should be as self-contained as possible. - -Split the work up in a granular fashion that makes each chunk as easy as possible to pick up and work on — for example fix one error, or write one page. Inside each issue, provide instructions for doing the work, or link to them. - -For example, instructions for creating a new reference page might look like this: - -- This issue relates to the workstream defined at `https://xxxxx` (link to overall project summary). -- Feature X is defined in this spec: `https://xxxxxxx`. -- This page should be created at `https://developer.mozilla.org/xxxxxx`. -- Use `https://xxxxxx` as a template for the page. -- Create a new source page in the content repo and test it locally using the instructions available at `https://github.com/mdn/content`. -- Once the page has been created, submit the changes as a pull request and wait for a review. - -Each issue should also have a reviewer assigned. - -Each issue should be given a specific label of the form "Workstream:xxxx", so that it is easy to filter for all related issues. - -Think of other contributors that might be looking for a bit of work to do, not just the existing personnel who are already invested. - -### Create project board - -Each workstream should have its own project board, created under . All of the individual work item issues should be listed on this board, as well as the overall project summary. - -The board title should describe the project succinctly, as well as containing the due date for completion of the project, as a reminder to those working on it, e.g. "Restructuring the mixin docs (March 15th)". - -The columns on each board should be as follows, from start to end: - -- Summary: Include the overall project summary card, and nothing else, in this column, so it is easy to find. -- Not ready: A place to put issue cards that have been started but are not ready to work on yet. -- To do: Issue cards that are ready to work on, but have not yet been started. -- In progress: Issues that are in progress. -- Needs review: Issues where the work is complete, and so are ready for review. -- Done: Issues that are complete. - -## Running a project - -Once you have done the project setup work, as listed in the above section, moving forward with running the project should be fairly straightforward. - -### Set up a regular checkin meeting - -The project lead should set up a weekly checkin time, ideally a video or voice call, although a text-based chat would do. In this call, the project team should: - -- Report on what they've been doing since the last meeting. -- Look at the actual work speed compared to the required speed for meeting the deadline, and adjust their work speed as required (only slip the deadline as a last resort). -- Talk through any problems that have come up, and make any necessary changes (e.g. does new work need adding, are there any blockers that need escalating, does existing work need rescoping?). -- Make sure everyone knows what they need to do next. The project lead should be responsible for agreeing and setting work items (assigning issues), and indeed in the first meeting some time should be set aside for deciding what everyone will work on first. - -### Ongoing work - -Go ahead with the project, doing the work as required, and meeting regularly to make sure everything is moving forward. - -Work organization: - -- When you start work on an issue, remember to put your work item in the "In progress" column on the project board. -- When an item is ready to review, put it in the "Needs review" column. If there is not a reviewer assigned, bring it up with the project lead. If it hasn't been reviewed for a few days, politely remind the reviewer, and bring it up in the regular project meeting if it is delayed for longer. -- Get the project lead to sign off on work items by @-mentioning them in the issue when it looks like everything has been approved, and getting them to do a final check, merge, and move the item to the "Done" column. - -### Final check - -Once all issue cards are done, the project lead should go through all the cards and give them all a final check before signing off on the entire workstream.