From c34d487f928cb494f3adf84d9e6d0ef43499e7a9 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Mon, 8 Mar 2021 18:00:12 +0000 Subject: [PATCH 1/2] adding shared processes --- .../processes/content_bug_triage/index.html | 163 ++++++++++++++++++ .../workstream_assessment_project/index.html | 150 ++++++++++++++++ 2 files changed, 313 insertions(+) create mode 100644 files/en-us/mdn/contribute/processes/content_bug_triage/index.html create mode 100644 files/en-us/mdn/contribute/processes/workstream_assessment_project/index.html diff --git a/files/en-us/mdn/contribute/processes/content_bug_triage/index.html b/files/en-us/mdn/contribute/processes/content_bug_triage/index.html new file mode 100644 index 000000000000000..27180e0246c5a12 --- /dev/null +++ b/files/en-us/mdn/contribute/processes/content_bug_triage/index.html @@ -0,0 +1,163 @@ +--- +title: Triage process for MDN content bugs +slug: MDN/Contribute/Processes/Content_bug_triage +tags: + - MDN + - MDN Meta + - Meta + - Meta Docs + - Content bugs + - Process + - Triage +--- +

{{MDNSidebar}}

+ +

This document looks at the process for triaging content bugs and getting them ready for contributors to effectively work on.

+ +

Reporting and working on bugs

+ +

Anyone can report a content bug by writing an issue at https://github.com/mdn/content/issues/new using the "Content bug" issue template, or by using the "Report a problem with this content on GitHub" link at the bottom of each MDN page.

+ +

Once reported, content bugs are listed at https://github.com/mdn/content/issues, and are designed to be done by individuals with minimal process requirements. Anyone is welcome to work on a content bug, using the process outlined at Fixing MDN content bugs.

+ +

Overall triage process

+ +

At a high level, the process for triage looks like so:

+ +

Triage preparation:

+ + + +

Triage for each issue:

+ + + +

Check through old bugs — look at existing bugs, and see if there are any that are stalled, or need closing, etc.

+ +

Triage preparation

+ +

Decide on triagers

+ +

We need an assigned triager to regularly triage bugs coming in on each MDN content area. We currently have the following triagers assigned:

+ + + +

Set initial labels

+ +

As soon as a new issue is filed, the MDN core team, and anyone else who wishes to help, will add the following labels to that issue: + +

+ +

Set aside triage time

+ +

Triagers don't need to be actively triaging bugs all the time. Instead, they should set out a 30-minute slot in which to triage the bugs in their area of responsibility, each week.

+ +

This doesn't have to be done as part of a synchronous meeting, or even at the same time as everyone else, but it should be done regularly, say once per week, to make sure that the backlog of untriaged bugs doesn't get too high.

+ +

Triage process for each issue

+ +

Checklist to determine if we have enough information

+ +

For each bug, run through the following checklist to make sure the issue contains enough information for someone to start working on the bug.

+ +

Does the issue contain:

+ + + +

If this information is not present, then the triager should ask the submitter of the issue to provide these details, and not continue triaging the issue until those details are provided.

+ +

Set priority measure

+ +

For each bug, set a priority measure label to help people who want to work on the most important issues or areas (rather than the topics they are interested in).

+ +

The levels of priority are:

+ + + +

Definitions:

+ + + +

Generally speaking, critical issues should be fixed immediately, and would probably be handled by MDN staff/peers. And Tier 1 issues are more important than Tier 2 issues. Folks that are interested in tackling the highest priority MDN issues should always tackle Tier 0 issues if any are available, before moving on to Tier 1 then Tier 2 issues.

+ +
+

Note

+

For definitions of Tier 1 and Tier 2, see the MDN documentation priority list.

+
+ +

Provide further information

+ +

It is really useful for other contributors to provide them with further information to help them fix issues; we'd like to recommend that triaging each bug involves a time-box of up to 5 minutes in which the triager quickly describes some steps to take to fix the bug, to help the person who eventually tries to fix it.

+ +

For example:

+ +
To whoever fixes this issue, it looks like the following is needed:
+
+* Update the first paragraph below heading X to correct the problem with Y
+* Add a description of X
+* Update the compatibility data at Link-X
+ +

Set other labels

+ +

Next, set other labels as appropriate:

+ + + +

Check through old issues

+ +

At the end of your triage session, have a look through the older existing triaged issues in your topic area, and check to make sure none of the issues are being unnecessarily stalled or clogged up:

+ + diff --git a/files/en-us/mdn/contribute/processes/workstream_assessment_project/index.html b/files/en-us/mdn/contribute/processes/workstream_assessment_project/index.html new file mode 100644 index 000000000000000..e4c938fdcfbadf3 --- /dev/null +++ b/files/en-us/mdn/contribute/processes/workstream_assessment_project/index.html @@ -0,0 +1,150 @@ +--- +title: MDN Workstream assessment and project setup process +slug: MDN/Contribute/Processes/Workstream_assessment_project +tags: + - MDN + - MDN Meta + - Meta + - Meta Docs + - Content bugs + - Process + - Workstream + - Assessment + - Project +--- +

{{MDNSidebar}}

+ +

Workstreams are larger, more involved MDN projects that are designed to be done by multiple people (across orgs) 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. 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 or openwebdocs project repos. These issues are given a preliminary quick assessment by a core team member to assess suitability.
    2. +
  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 https://github.com/openwebdocs/project/issues/26. +
      +
    • Note that in the "Priority assessment" table, each opportunity needs to be assessed against our prioritisation criteria.
      • +
    • For each criterion, give the project a description as well as a rough score of none/small/medium/large.
      • +
    +
    3. +
  3. Each month, we hold the opportunity assessment meeting to assess new opportunities, and record the results in the content opportunities spreadsheet. To be discussed in a meeting, each assessment needs an RFC submitted, to act as the basis for our discussion.
    4. +
  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 "213".
      • +
    • 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. +
  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 OWD 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 ad 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. +
  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.
    7. +
+ +
+

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 repo, to act as a focal point and summary for the prject work.

+ +

This should include:

+ + + +

Add to shared project roadmap

+ +

Each workstream should be added to the shared project roadmap (which currently lives in the High-level MDN schedule 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 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:

+ + + +

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 https://github.com/mdn/content/projects. All of the individual work item issues should be listed on this board, as well as the overall project summary.

+ +

The board title should 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:

+ + + +

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:

+ + + +

Ongoing work

+ +

Go ahead with the project, doing the work as required, and meeting regularly to make sure everything is moving forward.

+ +

Work organization:

+ + + +

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.

From 317238ef74ed8f26e268d250163c97b9accf8fcc Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 9 Mar 2021 13:08:55 +0000 Subject: [PATCH 2/2] making changes to address Ryuno-Ki comments --- .../processes/content_bug_triage/index.html | 10 +++++----- .../workstream_assessment_project/index.html | 18 +++++++++--------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/files/en-us/mdn/contribute/processes/content_bug_triage/index.html b/files/en-us/mdn/contribute/processes/content_bug_triage/index.html index 27180e0246c5a12..5ccafc6aefa4a3a 100644 --- a/files/en-us/mdn/contribute/processes/content_bug_triage/index.html +++ b/files/en-us/mdn/contribute/processes/content_bug_triage/index.html @@ -28,7 +28,7 @@

Overall triage process

@@ -61,7 +61,7 @@

Decide on triagers

  • Learn:Express / Learn:Django — Hamish Willee
  • Media — Ruth John
  • Other — Chris Mills
    • -
  • SVG — Andre Janische
    • +
  • SVG — André Jaenisch
  • WebAPI — Ruth John
  • WebExt — Caitlin/WebExt team
    • @@ -71,14 +71,14 @@

    Set initial labels

    As soon as a new issue is filed, the MDN core team, and anyone else who wishes to help, will add the following labels to that issue:

    Set aside triage time

    -

    Triagers don't need to be actively triaging bugs all the time. Instead, they should set out a 30-minute slot in which to triage the bugs in their area of responsibility, each week.

    +

    Triagers don't need to be actively triaging bugs all the time. Instead, they should set out a 30-minute slot in which to triage the bugs in their area of responsibility, each week.

    This doesn't have to be done as part of a synchronous meeting, or even at the same time as everyone else, but it should be done regularly, say once per week, to make sure that the backlog of untriaged bugs doesn't get too high.

    @@ -145,7 +145,7 @@

    Set other labels

    Next, set other labels as appropriate: