Update meetings and team practices

.github/ISSUE_TEMPLATE/meeting-deliverables.md

@@ -7,37 +7,28 @@ title: "Deliverables Review Meeting: <YYYY-MM-DD>"
 
 # 2i2c Deliverables Review meeting
 
-This is a **30 minute** recurring meeting every two weeks on **Tuesday at 8:00AM Pacific time** (here's [**a timezone converter**](https://arewemeetingyet.com/Los%20Angeles/2000-01-01/08:00/2i2c%20Team%20Meeting#eyJ1cmwiOiJodHRwczovL2hhY2ttZC5pby9ZNVNCTXhWN1I2Q01xemVUWGdtNWtBIn0=), ignore the date!).
+This is a **30 minute** recurring meeting every **Tuesday at 8:00AM Pacific time** (here's [**a timezone converter**](https://arewemeetingyet.com/Los%20Angeles/2000-01-01/08:00/2i2c%20Team%20Meeting#eyJ1cmwiOiJodHRwczovL2hhY2ttZC5pby9ZNVNCTXhWN1I2Q01xemVUWGdtNWtBIn0=), ignore the date!).
 
 Our goal is to synchronize the team on the most important things to work on, and to divide work between one another so we know what to work on next.
 
 - **Video conference link:** https://bit.ly/zoom-holdgraf
 - **Calendar for future meetings:** [this Google Calendar](https://calendar.google.com/calendar/embed?src=c_4hjjouojd8psql9i1a8nd1uff4%40group.calendar.google.com&ctz=America%2FLos_Angeles)
-- **Meeting moderator**: <INSERT MODERATOR HERE>
+- **Meeting facilitator**: <INSERT FACILITATOR HERE>
+- **Meeting recorder**: <INSERT RECORDER HERE>
+- **Meeting timekeeper**: <INSERT TIMEKEEPER HERE>
 
 ## Meeting agenda
 
 _Follow the agenda below, checking boxes as we complete each step._
 
-### Activity Backlog
-_(5m) Quick review of [Activity Backlog](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) to let team members signal-boost if needed._
-
-- [ ] Team members signal-boost latest team sync items if they wish.
-- [ ] Note items that 2i2c team members wish to highlight for review.
-- [ ] Note important upcoming dates for the team.
-
-### Major deliverables
-
-_(20m) Overview major work items in our [Development Backlog](https://github.com/orgs/2i2c-org/projects/7?fullscreen=true)._
-
-- [ ] Discuss any high-priority items that need refinement.
-- [ ] Each 2i2c team member knows the next two things that they'll work on.
-- [ ] Each high-priority ready-to-work issue has at least one team member assigned to it.
-
-### Support steward transfer
-
-_(5m) Transition support steward roles to the next team member._
-
-- [ ] Preview support steward describes major support issues that have come up (with links to relevant issues)
-- [ ] Open issue for next Support Steward.
-- [ ] Close previous issue for Support Steward.
+- [ ] (5m) Quick review of [Activity Board](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) to track progress from last week.
+  - [ ] Team members signal-boost any issues/PRs/discussions if they wish.
+  - [ ] Note any deliverables that we didn't finish in the last cycle, decide what to do with them.
+- [ ] (20m) Populate [Activity Board](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) with new deliverables to work on for this cycle.
+  - [ ] Somebody assigned to each item on the Activity Board
+  - [ ] Everybody agrees the current cycle's plan is realistic that the right items are on the board.
+- [ ] (5m) Support ticket overview.
+  - [ ] Support steward asks for assistance on issues that need it.
+  - [ ] (_every two weeks_) Transition support steward roles to the next team member
+    - [ ] Open issue for next Support Steward.
+    - [ ] Close previous issue for Support Steward.

.github/ISSUE_TEMPLATE/meeting-team.md

@@ -29,7 +29,7 @@ _Steps to take to have the meeting._
 
 - **At least 1 day prior to meeting**
   - [ ] Agenda items added to the meeting
-  - [ ] Moderator and Note Taker identified in HackMD
+  - [ ] Meeting roles identified in meeting issue
 - [ ] Have the meeting
 - [ ] Open up any follow-up issues or discussions and link above
 - [ ] Cut notes out of HackMD and add to the Team Compass: <PR link here> 

.github/ISSUE_TEMPLATE/new-bug.md

@@ -12,7 +12,7 @@ labels: "type: bug"
 
 <!-- Describe what you expected or want to happen -->
 
-# Actions to improve this?
+# Actions to address this
 
 <!-- Add a list of actions that should be taken to improve this -->
 

.github/ISSUE_TEMPLATE/new-enhancement.md

@@ -8,23 +8,18 @@ labels: "type: enhancement"
 
 <!-- What is the context needed to understand this enhancement -->
 
-# User Stories
+# Benefit
 
 <!-- Who is this enhancement for? What need does it address? -->
 
+- This issue is important because...
 - As a `<type of user>` I want to `<do something not yet possible>` so that `<I get some kind of value>`.
 - ...
 
-# Acceptance criteria
+# Actions to complete
 
-<!-- When will we know that this enhancement is complete? -->
-
-- Given `<some scenario>`, when `<some action is taken>`, then `<a specific result happens>`.
+<!-- What actions are needed to make this enhancement? -->
 
 # Important information
 
-<!-- A bulleted list of important information or links -->
-
-# Tasks to complete
-
-<!-- What tasks are needed to make this enhancement? -->
+<!-- An optional bulleted list of important information or links -->

practices/development.md

@@ -2,105 +2,90 @@
 # Team development workflow
 
 This section describes how our development team carries out its planning and day-to-day work.
-Here's a quick summary:
 
-* [Deliverables](coordination:deliverables) are discrete units of value that we bring to others. To be ready for work, they should be scoped properly, with enough information to complete them (e.g., a set of [tasks](coordination:tasks)).
-* The [Project Backlog](coordination:project-backlog) contains lists of **deliverables** that we are currently working towards across all of the 2i2c projects. Deliverables on the Project Backlog define our team priorities at any moment.
-* [Tasks](coordination:tasks) are concrete actions to take, and should be accomplishable in a single work session by one person.
-* The [Activity Backlog](coordination:active-backlog) contains lists of **tasks** that we are currently working on. This defines 2i2c's current activity.
-
-(coordination:project-backlog)=
-## Project Backlogs
-
-The Project Backlog contains all of the deliverables across our projects that we wish to work on quickly.
-These are organized into a few columns, representing the _state_ of each deliverable.
-Here is a common column structure:
-
-- {guilabel}`Needs Discussion/Refinement`: Deliverables that are high-priority but un-refined. Our goal should be having discussion and doing research in order to get these deliverables ready for work.
-- {guilabel}`Ready to Work`: Deliverables that are well-scoped and have a clear path forward, and are thus ready to implement. As deliverables in {guilabel}`In progress` are completed, we should replace them with deliverables from this column. Generally speaking, deliverables near the top have higher priority than those at the bottom.
-- {guilabel}`In progress`: Deliverables that we are currently working towards. This means that we should be generating [Tasks](coordination:tasks) in our [Activity Backlog](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) to complete this deliverable (more on this below).
-- {guilabel}`Blocked/Waiting`: Deliverables for which we are waiting for some action that is out of our team's immediate control.
-- {guilabel}`Done`: Deliverables that have been completed. We should close these issues and celebrate the improvements that we have made!
-
-:::{note}
-In general, there should be only two or three deliverables per team member, per column on this board.
-It should not become so heavily-populated that it is hard to keep track of deliverables!
+:::{admonition} Helpful links
+👉 [Here is a link to all 2i2c GitHub Issues that have been assigned to you](https://github.com/issues?q=is%3Aissue+is%3Aopen+archived%3Afalse+sort%3Aupdated-desc+assignee%3A%40me+user%3A2i2c-org+)
+👉 [Here's a link to see all Pull Requests for which your review is requested](https://github.com/issues?q=is%3Aopen+archived%3Afalse+sort%3Aupdated-desc+user%3A2i2c-org+type%3Apr+review-requested%3A%40me+)
 :::
 
-There are two Project Backlogs at 2i2c:
-
-- The [2i2c Development Projects Backlog](https://github.com/orgs/2i2c-org/projects/7?fullscreen=true) contains deliverables for our development-focused projects.
-- The [Organizational Project Backlog](https://github.com/orgs/2i2c-org/projects/8?fullscreen=true) contains deliverables that are organization-wide and not related to development.
+## Cadence of work
 
+Our team works in one week cycles.
+Each cycle begins on Monday with our [team deliverables review meeting](meetings:deliverables-review).
+In this meeting we prioritize and assign the items that each team member will work on for the next week, and review items that require discussion and planning.
+At the end of each week, we should have completed all of the major delivearables set out for that week.
+
 (coordination:deliverables)=
 ## Deliverables
 
-Deliverables represent incremental amounts of value we can deliver to a particular stakeholder, and should be completable in a week or two.
+Deliverables represent incremental amounts of value we can deliver to a particular stakeholder, and should be completable in a week.
+They are **encoded as GitHub Issues**.
 
-Most issues in our repositories are deliverables, in varying states of readiness. When a deliverable is first created, it may lack information, be improperly scoped, or have an unclear path to implementation. We improve this through _deliverable refinement_ (see below).
+Most issues in our repositories are deliverables, in varying states of readiness.
+Deliverables that are added to the [Activity Board](coordination:activity-board) should have enough context and tasks that a team member can realistically close them on their own. [^invest]
 
-A deliverable is ready to work (and can thus be added to the Project Backlog) when it has the following properties (adapted from the [INVEST methodology](https://agileforall.com/new-to-agile-invest-in-good-user-stories/)).
+[^invest]: A good resource for considering what kinds of information makes a deliverable "ready" is [the INVEST methodology](https://agileforall.com/new-to-agile-invest-in-good-user-stories).
 
+:::{admonition} Deliverables should...
+:class: tip
 - **Have a short title and description:** Deliverables should be glanceable and have enough context that the reader can quickly understand the scope.
 - **Have one or more [user stories](https://www.atlassian.com/agile/project-management/user-stories):** User stories should define who benefits from the deliverable, and why they want it.
-- **Have completion criteria:** We have clear completion criteria for this deliverable to denote it as “done”.
 - **Have tasks to complete it**: Deliverables should have a set of tasks, which are actions needed to complete the deliverable.
+:::
 
-### How refinement happens
+(coordination:activity-board)=
+## The Activity Board
 
-_Deliverable Refinement_ is the process of improving the scoping, context, and structure of our Deliverables issues so that they are ready for us to work on them. When a deliverable is created, it may not have all of the information needed to take the next step. Adding that information is the goal of Deliverable Refinement.
+The [Activity Board](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) contains the collection of [Deliverables](coordination:deliverables) that the team is currently working on.
+All deliverables on the Activity Board should be accomplished by the end of the week.
+This board is filled during our [Deliverables review meeting](meetings:deliverables-review).
 
-All team members are expected to participate in deliverable refinement, though the more experienced and higher-level you are, the more you should be contributing to this process.
-The important thing is that we always have a list of high-quality deliverables ready to work towards.
+:::{admonition} The Activity Board should...
+:class: tip
+- Have enough deliverables to keep the team occupied for the week
+- Not have so many deliverables that a team member gets overwhelmed
+- Under-estimate our team's total capacity, to provide room for unexpected work (e.g., support work)
+- Have a team member assigned to each item on the board
+:::
 
-Here's a small table that explains how to decide whether deliverables issues should be put in a project backlog:
+The Activity Board is broken down into these columns:
 
-:::{list-table}
-:header-rows: 1
-- -
-  - Needs more information
-  - Ready for working
-- - Low priority
-  - Stays in issues
-  - Put in {guilabel}`Ready to work`
-- - High Priority
-  - Manually put in \
-    {guilabel}`Needs Discussion/Refinement`
-  - Put in {guilabel}`Ready to work`
-:::
+- {guilabel}`Up Next` Deliverables that are ready to be worked on.
+- {guilabel}`In progress` A deliverable that a team member is currently working towards.
+- {guilabel}`Done` Tasks that are complete! When you move a task here, make sure to update any relevant deliverables.
 
-(coordination:active-backlog)=
-## Activity Backlog
+## Requesting reviews
 
-The [Activity Backlog](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true) contains the collection of **Tasks** that the team is currently working on.
-Tasks are actions that are needed to accomplish some deliverable.
-These tasks are generated from the deliverables on the Projects Backlog.
-They define a “to do” list of tasks to complete on a day-to-day basis.
+When you have an implementation that requires feedback, use GitHub's **Request Review** feature to ask other team members to take a look.
+You can either add all team members as a request, or add specific team members if you believe they'll be particularly helpful in a review.
 
-The Activity Backlog is broken down into these columns:
+% TODO: We should define a more structured process for requesting reviews and how it fits in with our merge policies.
 
-- {guilabel}`Needs Discussion/Refinement` Tasks that require some team discussion around _implementation_. If there are higher-level discussions about the deliverable itself, perhaps the deliverable is not yet ready to be worked on.
-- {guilabel}`Ready to Work` Tasks that are ready to be worked on. Roughly speaking, tasks higher on the list are of higher priority.
-- {guilabel}`In progress` A task that a team member is currently working towards. When you move a task to In progress, indicate that you are working on it (either by adding your username to the card, or “assigning yourself” in the issue/PR associated with it.
-- {guilabel}`Needs review` Tasks that have an implementation that require feedback from others. For example, reviews for pull requests.
-- {guilabel}`Done` Tasks that are complete! When you move a task here, make sure to update any relevant deliverables.
+## Encoding longer-term efforts
 
-There is one Activity Backlog defined [at this GitHub Projects Board](https://github.com/orgs/2i2c-org/projects/5?fullscreen=true).
+Longer-term projects are generally more complex and may be made up of many actions and deliverables to accomplish.
+There is no official way to track long-term projects within 2i2c, but there are a few patterns that may be useful to do so.
 
-(coordination:tasks)=
-## Tasks
+% TODO: We should define a more reliable process for tracking long-term projects
 
-Deliverables of sufficient complexity are broken down into _tasks_. Tasks should be completable by a single person in less than one day (generally, completable with a few hours of focused work at most). Make sure to attach a link between your deliverable and its tasks (e.g., by adding links to issues in the deliverable’s "tasks" checklist)
+### Tracking issues
 
-Tasks are generally encoded as checklist items in a deliverable, then added to the Activity Backlog when the deliverable is being worked on.
+The simplest way to track longer-term efforts is with a **Tracking Issue**.
+This is a GitHub Issue whose job is to keep track of many actions and deliverables over time that are needed to close the issue.
+They are generally encoded as **Task Lists** in the issue's top comment.
+Each item in the list tends to be a deliverable, and can be converted into its own GitHub Issue (e.g., to put on the [Activity Board](coordination:activity-board)) as-needed.
 
-Here’s an example of a deliverable with a few tasks:
+(coordination:project-backlog)=
+### Project Backlogs
 
-- **Deliverable:** Side notes in Jupyter Books. \
-  **User story**: _As a book author, I want to be able to create “aside” content that does not break up the narrative flow of my text._ \
-  **Tasks:**
-    - Create design doc for directive name and general API
-    - PR to prototype functionality and documentation
-    - Add tests and QA
-    - Final approval + merge
+For more complex efforts, it can be useful to create a Project Backlog.
+These are GitHub Projects boards that contain all of the deliverables that will complete a given project.
+These are often organized into a few columns, representing the _state_ of each deliverable.
+Here is a common column structure:
 
+- {guilabel}`Needs Discussion/Refinement`: Deliverables that are high-priority but un-refined. Our goal should be having discussion and doing research in order to get these deliverables ready for work.
+- {guilabel}`Ready to Work`: Deliverables that are well-scoped and have a clear path forward, and are thus ready to implement. As deliverables in {guilabel}`In progress` are completed, we should replace them with deliverables from this column. Generally speaking, deliverables near the top have higher priority than those at the bottom.
+- {guilabel}`In progress`: Deliverables that we are currently working towards. This means that they should be added to the [Activity Board](coordination:activity-board) to track its completion.
+- {guilabel}`Blocked`: Deliverables that require another action or delivearable from the 2i2c team to complete before they can move forward.
+- {guilabel}`Waiting`: Deliverables that require another action from a **non-2i2c team member** before they can move forward.
+- {guilabel}`Done`: Deliverables that have been completed. We should close these issues and celebrate the improvements that we have made!