Technical decision making/Background

This process should be used in any circumstance where the impact of the decision will be felt beyond the team making that decision. This especially includes decisions that impact code and software deployed on Wikimedia production infrastructure.

Summary
Below is a process for how technical decision are made. This process was adopted in 2020 as an evolution of the legacy TechCom process.

Key objectives of this process are:


 * Make the process more inclusive by shifting to representation by teams/groups instead of individuals
 * Have clear timelines for when a decision will be made
 * Being clear upfront about what stakeholders will be engaged
 * Developing a clear lifecycle of a decision

This process includes:


 * Technical Decision Forum which will be composed of representatives of teams from Product and Tech, WMDE and independent +2 contributors.
 * Templates for decision statement overviews and decision records

Decision Team Identification or Creation
The Decision Team is the group driving the decision. In most cases this will be an individual team, volunteer group or affiliate. But there are certain decisions, similar to the decision to implement Vue.js (JavaScript Framework), that are more cross cutting where the team might be made up of a cross section of people. It is crucial that who is accountable for the decision is resourced (have a clear way to execute the decision) and they have the authority to act on that decision.

Decision Statement Overview (1 week)
A document which describes the decision to be made. This is tagged with the Technical Decision Making board in Phabricator.

STEP 1: CREATE 'Decision Statement Overview' task in Phabricator. [Decision Team]

You can use [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?title=%7BName%20the%20Problem%2FOpportunity%7D&owner=Jenlenfantwright&description=%2F%2FInstructions%20%20%2F%2F%0D%0A%20%20%23%20Define%20the%20problem%20or%20opportunity%20(WHAT).%0D%0A%20%20%23%20Outline%20the%20importance%20of%20addressing%20the%20problem%20or%20opportunity%20(WHY).%0D%0A%0D%0A%3D%20WHAT%3F%0D%0A**Write%20your%20problem%20statement%20using%20layperson%E2%80%99s%20terminology.%20%0D%0AIn%20one%20sentence%2C%20what%20is%20the%20problem%20or%20opportunity%3F**%0D%0A%2F%2FNetflix%20Problem%20Statement%20Example%3A%20Going%20to%20the%20video%20store%20requires%20fighting%20traffic%2C%20wandering%20the%20aisles%2C%20and%20waiting%20in%20long%20lines%20just%20to%20get%20a%20single%20movie.%2F%2F%0D%0A%20%20-%20%0D%0A%20%20-%20%0D%0A%20%20-%20%0D%0A%0D%0A**What%20does%20the%20future%20look%20like%20if%20this%20is%20achieved%3F%20**%0D%0A%20%20-%20%0D%0A%20%20-%20%0D%0A%20%20-%20%0D%0A**What%20happens%20if%20we%20do%20nothing%3F**%0D%0A%20%20-%20%0D%0A%20%20-%20%0D%0A%20%20-%20%0D%0A%0D%0A%3D%20WHY%3F%0D%0A**Identify%20the%20value(s)%20this%20problem%2Fopportunity%20provides.%20Add%20links%20to%20relevant%20OKRs.%20**%0D%0A%2F%2FRank%20values%20in%20order%20of%20importance%20and%20be%20explicit%20about%20who%20this%20benefits%20and%20where%20the%20value%20is.%2F%2F%0D%0A%0D%0A**User%20Value%2FOrganization%20Value%20AND%20Objective%20it%20supports%20and%20How**%0D%0A%0D%0A%20%20%23%20%0D%0A%20%20%23%20%0D%0A%20%20%23%20%0D%0A%20%20%23%20%0D%0A%0D%0A**Why%20are%20you%20bringing%20this%20decision%20to%20the%20Technical%20Forum%3F**%0D%0A%2F%2FWhat%20about%20the%20scope%20of%20this%20problem%20led%20you%20and%20your%20team%20to%20seek%20input%20across%20departments%2Forganizations%3F%2F%2F%0D%0A%20%20-%20%0D%0A%20%20-%20%0D%0A%20%20-%20%0D%0A%0D%0A&projects=tech-decision-forum&subscribers=Jenlenfantwright&priority=triage this Phabricator task template] to create the task.

STEP 2: Technical Decision Forum Project Manager copies the submitted 'Decision Statement Overview' task in Phabricator into a Google Doc and shares it with the project owner who submitted it and the Technical Decision Forum Chairs to review, add comments and discuss. Below is the template for the Google Doc that will be used for real-time collaboration during this stage of the process. The Technical Decision Forum Project Manager will add a link to the Decision Statement Overview Google Doc to the initial phabricator task when the project owner is ready to share it.

Template: Decision Statement Overview


 * Define the problem or opportunity (WHAT).
 * Outline the importance of addressing the problem or opportunity (WHY).



Touch Points:
 * Phabricator Workboard (with overview template)
 * Office Hours (available by appointment biweekly)

Technical Decision Forum
The Decision Statement Overview is shared with the Technical Decision Forum by adding a phabricator ticket to the Decision Forum Inbox. The Project Manager of the forum will monitor phabricator and send process emails to the forum when there are new overviews.

The Technical Decision Forum is made up of people representing individual teams, organizations or volunteer groups. The Forum is chaired by a representative from the Technology Department and one from the Product Department, the chairs are rotated on a quarterly basis. Teams may rotate their representation as needed, but the expectation is that feedback on the artifact can be provided within a week. The feedback requested at this point is as follows:


 * Is the problem statement correct?
 * Is it clear how solving this problem moves forward our organizational goals (supports, Movement Strategy, the Medium Term Plan, Annual Plan, etc…)?
 * Are these the right stakeholders?
 * Is the needed subject matter expertise to make a decision reflected accurately? Are the right groups outlined in the overview?

Touch Points:


 * Office Hours
 * Technical Decision Forum Google Group
 * Phabricator
 * Google Docs
 * Slack

Research and Prototyping Stage (Timeboxed with check-ins every two weeks)
Once the Decision Statement Overview is confirmed with the Technical Decision Forum, the Decision Team begins work and demos/checks in with the Technical Decision Forum every two weeks. Here is where options and solutions are developed. This phase should be scoped and timeboxed. At the check-in they demo progress being made to inform the decision. This is the time where stakeholders are engaged with, further models are developed and prototyping occurring as needed.

''Note: Demonstrations do not have to be prototypes with UIs. They could be a summary on progress on a document, pseudo code or anything else that helps others see where the team's progress and thinking is at that time.''

Touch Points:


 * Technical Decision Forum
 * Demonstrations during Office Hours
 * Retrospectives
 * Phabricator
 * Progress Announcements in Technical Decision Radar

Executive Review (Depends on the scope of the decision)
For larger, more impactful decisions, system-level tradeoffs or decisions that greatly impact the community, demonstration of the overview is done for relevant executives, typically the Chief Technical Officer (CTO) and Chief Product Officer (CPO). The CTO and CPO will delegate a representative that will review the Decision Overview and flag for review with the CTO and CPO when it is believed it might meet the requirement for Executive Review.

Touch Points:


 * Meeting with Executives

Make the Decision
Once the Decision Team has engaged all the stakeholders outlined in the Decision Statement Overview and reviewed with Executives (as required) the team can make the decision.

Touch Points:


 * Technical Decision Forum
 * Phabricator
 * Decision Announcement in Technical Decision Radar

Decision Record Published
Once a decision has been made it is published on MediaWiki here.

Retrospective
Retrospectives are held on a twice quarterly basis to review the decision-making process.

Technical Forum
Logistics and membership page

Guidelines for when to use the process
This process should be used in any circumstance where the impact of the decision will be felt beyond the team making that decision. This especially includes decisions that impact code and software deployed on Wikimedia Production Infrastructure.

Artifacts






Decision Type Matrix
Below are typical decisions from the existing RFC process. These decisions are outlined here to ensure they are not lost in the transition. Some decisions are outside the scope of this process and a new responsible party is proposed. Both the type of decision and the group that should be responsible for driving this type of decision are outlined below. Some items such as the product specific decisions are not technical in nature and should be made by Product rather than in this process.

Why?
To evolve the TechCom RFC process to a more explicit decision making process that allows teams and other stakeholders to have a clear understanding of:


 * What types of decisions must utilize this process
 * What the timeline expectations are for that process
 * Who the stakeholders are that should be engaged in their decision
 * The lifecycle of a decision: a problem being raised -> decision being made -> published -> revisited -> iterate and improve

Currently, many cross cutting technical decisions are shepherded by TechCom. TechCom has lacked the resourcing to be proactive about decisions and all necessary stakeholders aren’t always represented. This shift is designed to take the best parts of the TechCom process and improve upon the challenges. It is also intended to allow iteration. The first release doesn’t propose to improve every single aspect of the existing process, but does have the goal to make those aspects at least equal with the status quo. The change will ensure decisions are being driven by teams or groups fully committed to completing the work, that problem statements are defined early and stakeholders are outlined. This proposal is also designed to remove gatekeeping by ensuring people are consulted rather than giving explicit approval. Following is a review of the successes and difficulties of the existing TechCom process. In shifting this process we do not want to forget the successes but also want to improve on the challenges.

Successes of the TechCom RFC Process


 * Clear place to ask for a decision
 * Process occurs transparently on Phabricator
 * TechCom Radar summarized discussions going on
 * Defined process
 * Identifies many stakeholders during the process

Challenges of the TechCom RFC Process


 * Not always clear who is driving the decision and when a decision will be made
 * Viewed and reacted to as gatekeeping
 * Sometimes stakeholders are missed
 * Often TechCom is brought in late in the process
 * Solutions are brought forward without a clear problem statement/stakeholders not agreeing on what problem is being solved
 * TechCom does not have inclusive membership
 * Not a clearly resourced committee
 * Project Management of process not clearly resourced

Transition Process
This variant of the process was piloted with Vue.js decisions. During that time the Technical Decision Making Process/Forum and TechCom both existed. TechCom will continue to be responsible for other decisions beyond the work of the Vue.js Taskforce per the existing TechCom Charter. Having both exist at the time allows for trial and iteration on this process on a small scale before using it for a wider range of decisions.

Once the pilot is finished all technical decisions and TechCom will be transitioned to the Technical Decision Making Process. TechCom members may serve as representatives of their teams on the Technical Decision Forum if that is what their team decides.

What happens to existing RFCs?

There will be a two week grace period after the Technical Decision making process and Technical Decision Forum is set-up for groups to claim their existing RFCs. After the two weeks the remaining Phabricator tasks that are purely RFCs will be closed and the TechCom-RFC board will be archived. Other tasks that are tagged as RFCs but contain other work will be triaged and untagged as an RFC and requested be moved to the next decision making process if appropriate. The tickets can always be reopened and transitioned to the new document format if they are still relevant.

Resources

 * Open Decision Framework
 * Farnam Street Decision Making Course
 * Wikipedia Article on Consensus
 * GEODE RFC Process
 * Eigenquestions: The Art of Framing Problems
 * Decisive Dan and Chip Heath
 * Forum contact [mailto:tech-decision-forum-support@wikimedia.org tech-decision-forum-support@wikimedia.org]