Product Tech Steering Committee

This document describes a process within the Wikimedia Foundation that lets client developers easily request new APIs to support their work.

Background
In July 2020, as part of the Product and Tech team collaboration annual plan, the Product and Platform departments formed a working group to improve cross-team collaboration with a focus on API initiatives. The group agreed on an objective to “define a process for aligning goals and assigning work for API development.” To achieve this objective, members identified the following four key results:


 * KR1: We implement a process to prioritize and manage API development across teams
 * KR2: The workflow is mapped with a visualization
 * KR3: A Phabricator board set up to implement the process
 * KR4: Written learnings about the process in development.

This present document describes the process from the API pre-request to product delivery.

Scope
This process focuses on API initiative prioritization only. It does not cover any other product initiatives the Platform Engineering, Product Infrastructure and/or Architecture teams work on with the Product Department, which may fit into the suggested workflow but are outside the working group’s current mandate.

Goals
The goals of this process are to:


 * Have a transparent decision-making process for Product and Platform teams
 * Set timeframes for decision-making
 * Identify team representatives
 * Facilitate cross-team collaboration

Process
Although there’s an oversight committee, the development and client teams work hand-in-hand throughout the process, iterating on specifications along the way. We expect this process to evolve overtime.

0. Pre-Request Product Process
Who is responsible: Requesting team in partnership with platform

These are all steps that should happen prior to making an API request. It might be that, after following these steps, an API request is not made.

1. API Request Made
The Product team submits an API initiative request by creating a Phabricator ticket in the Untriaged column on the Platform-Product Roadmap Workboard here, ideally no later than 3 months before stakeholders expect to start using the API to give the team responsible for building the API enough time to plan and execute. As stated earlier, the development and client teams work together to build the API, including frequent client reviews, feedback, and demos throughout the API initiative implementation.

The Phabricator request ticket must include the timeline, vision, target groups, needs, products, API attributes, and aligned goals/OKRs in the description.

All steering committee members join the Tech-Product API Roadmap Phabricator project as watchers to receive notifications when other users make changes to the Phabricator workboard.

2. Initial review
As part of the initial review, Seve, Evan, API EMs or Tech Leads, and the Client team representative (ideally Product Manager or Tech Lead) review the request to clarify and open questions and issues that have an impact on prioritization. This might include things like scope boundaries, security, performance, and anything that might be affected by this being implemented. The outcome of the initial review is that Seve and Evan understand what is being asked of and can call out any known red flags or areas of concern. Once the card has been reviewed, the ticket will be moved from the “Untriaged” column to the “Reviewed” column ready for prioritization and team assignment.

3. Prioritization and Team Assignment
The following will be part of the steering committee in order to make the decision on how to move from the “Reviewed” column to one of the “Later”, “Now” or “Next” columns.


 * Evan Prodromou
 * Seve Kim
 * Jon Katz
 * Danny Horn
 * Will Doran
 * Daniel Cipoletti
 * Mat Nadrofsky
 * Optional: Client Team representative
 * Optional: OKAPI team representative
 * Optional: Architecture team representative

In order to make the decision to prioritize on the upcoming roadmap, the following are a non-exhaustive list of criteria that is considered:


 * What is the client timeframe?
 * What is the size of the API (endpoints)?
 * How many client teams need this API?
 * What is client priority? What is the departmental priority?
 * Is the API reusable by internal or external teams?
 * Is there a team available to build this?
 * Do we have skills to build the API?
 * What is the level of risk?
 * Why should we work on this next?
 * Why should we work on this later?

In addition to establishing what the priority of the work is, the team selection for who will do the work needs to be decided on. In the process of selecting the team to take on this work, the skill sets, team capacity and knowledge also needs to be taken into account.

As in most cases, either the Platform Engineering team or Product Infrastructure will be first considered for the work. There is no hard and fast rule between whether work should be given to either of these teams and the hope is that a more defined boundary emerges over time. Depending on the some of the considerations when selecting the team, a few example cases are:

Architecture Proof of Concept
If there is an architecture proof of concept, it is most likely to have the Architecture team be slated to commit to the work.

Potential Commercial Usage
If there are aspects in which the API could have commercial usage, the OKAPI team could be best to take development on.

Client-Specific
A front-end team, such as Android, could be best to maintain ownership over services that are uniquely geared towards their mobile platform.

Team Familiarity
The team being considered has shipped something similar before or has high familiarity with the existing technology or interface.

ML?
Other artifacts that can be leveraged in the team selection process:


 * Phabricator board
 * Product Infrastructure skills matrix
 * Platform Engineering skills matrix
 * Architecture skills matrix
 * Security skills matrix
 * Platform skills matrix.

4. Handshake
Once the steering committee has decided on the request of the API, the slated team will circle back the client team that submitted the request to align on timeline, scope and “shake hands” to get agreement on what outcome the client team expects.

Coming out of this meeting, the expectations are that a written specification is agreed upon by both parties, client and platform alike. In the event of a prototype, then there should be explicit success metrics required that signify this API should be continually maintained. Likewise, there could also be conversations in this meeting around system architectural upgrades.

5. Principles on Collaboration
At this point, both client team & tech team move forward with their process. The expectation on how teams collaborate are supported by the following principles:

Continuous Communication
Clients and API teams are expected to meet, communicate and stay updated on a regular basis. Any changes to the specifications or requirements should be brought up as early as possible in order to reduce the impact of changes needing to be made.

Strive for Self-Service
In order to ensure autonomy and streamlined implementation for the Client Teams, APIs should be easy to use without being dependent on API teams for help or clarification. This means having an understandable API with clearly named endpoints, all documented with examples.

API Teams Own Reporting & Dependencies
API teams should own and drive the progress against the agreed upon timeline and deadlines. Updates as to release notes and versioning changes should be coming from those teams. Likewise, the API teams are accountable for running all relevant issues past security, performance and legal (often in coordination with the Client Team).

Consider the Whole Lifecycle
As the work is starting to take shape, there should be a strong lean towards non-proliferation of APIs. There should be thought in whether existing APIs can be extended to meet new use cases. Also, considering if new use cases aren’t met by old APIs, thus planning for deprecating entirely.

Warranty
Should there be any problems and requested changes needed post-deployment, there should be an agreed upon support buffer that the API teams should be providing in a set time.

Process Visualization
The process flow below articulates the entry and various exit points along with how work flows through our process at a high level.

FAQ

 * What constitutes as a valid "API request" for this process?
 * Any request that has an expected outcome to a problem is valid. The solution, however, can be an existing API, a net new API, deference to an appropriate team that has a solution, or a combination.

Open Questions

 * How do we choose which team does the work? (e.g. Product Infrastructure or Platform Engineering?)
 * What are we not covering in this process and why?
 * How do we work with other teams? (e.g. Research, ML, etc.)
 * How are defining the ownership and ongoing maintenance of the things getting built?
 * Is this an interim solution or this is the indefinite right way to do this from now on?