Technical Collaboration Guidance/Vision

The Technical Collaboration Guideline aims to become a set of recommendations followed by Wikimedia Foundation Product teams and Wikimedia communities to partner in software development. This document describes the pieces involved in this collaboration, and how they can work together.

Development flow
Imagine Development river flowing quietly but decidedly from the Lake of Ideas to the Sea of Deployments.

Imagine Project boats following the current or sailing up in this navigable river without waterfalls.

Imagine bridges across the river, each one a specialized Checkpoint, where people interested can watch Project boats as they approach.

Project boats show their decks while crossing slowly under the Checkpoints, and continue their journey if nobody raises objections.

When objections are raised, they are discussed with the crew, who may stop the boat to fix the problems or sail back to previous stages.

Sometimes Project crews and some watchers agree to disagree. The crew takes note, hands are shaken, and the journey continues. They will meet again at the river mouth, before entering the Sea of Deployments.

At the Bay of Communities, hundreds of settlements can be seen. Project boats visit first the communities that want to be visited first, and continue with the silent majority.

Finally, Project boats visit the communities with issues still unresolved. Hands are shaken again, discussions are held again, and at the end these communities decide whether the issues are resolved or whether a new visit in the next season is still in order.

Starting a project
Starting a project with the goal of deploying it in Wikimedia is a very serious matter, directly proportional to the user impact and expected budget. The more disruptive and expensive the plan, the more it is required to be checked against the mission, principles, strategy, annual plans, supported technologies...

The development flow needs to allow room for experimentation. Without experimentation, Wikimedia would not exist. Small adventures from idea to prototype are encouraged, as long as it is understood that the route from prototype to deployment will be more complex, and may not happen at all.

Checkpoints
Product teams work better in an agile context where experimentation, iterations and flexibility are the norm. Volunteers in wiki communities can understand these principles well, but they cannot afford to participate in the daily life of projects. Checkpoints allow projects to get the communities and other stakeholders involved, influencing their next steps.

Checkpoints happen when a project has a new deliverable that welcomes public feedback:
 * 1) A project proposal.
 * 2) A design concept.
 * 3) Translatable content.
 * 4) A prototype.
 * 5) A release plan.
 * 6) A beta in production.

Calls for feedback
Projects make calls for feedback at every checkpoint. They do it in a systematic way, using the same channels and the same principles for processing feedback and deciding next steps.

Volunteers can subscribe to all calls for feedback from a specific project (i.e. Flow). They can also subscribe to all calls of feedback of a certain type (i.e. design reviews). This allows the participation of more volunteers with limited time, interested in a specific project or focus.

The calls for feedback are common to all stakeholders, including communities and other WMF teams.

Ideally, calls for feedback should include calls for contributions as well, pointing to tasks that welcome volunteers.

Blockers
Calls for feedback focus on finding potential blockers. Smaller problems and requests are also welcome, but they will be put aside when potential blockers are found.

Blocking a project is a serious matter. Blockers proposed need to have a solid argumentation. They must be discussed until a decision is made. Blockers can be declined by the project team, who will need to provide a solid argumentation too.

Project information
All projects have a wiki page with an overview and a standard infobox containing their basic information: Phabricator links, contact details, subscription, and checkpoints passed / pending. Users can follow the checkpoint links to understand quickly the development status of a project.

Checkpoint information
All checkpoints have a wiki page with an overview, subscription, and up to date information about the projects that are running a call for feedback and the ones that passed/failed it.

Community decisions
Communities have two ways of controlling the products and major features deployed in their wikis:
 * 1) Timing of the deployment, requesting to be among the early adopters or among the late / last adopters. Most features are deployed by waves, and this provides flexibility to projects very interested or very skeptical about a specific feature.
 * 2) Opt out, based on blockers reported that have clear community consensus. The hypothesis is that most of these blockers will either be solved through deployment waves, or will stand and stop a feature for all Wikimedia projects.

Boats on rivers
This analogy is not about collaboration, but about gatekeeping: I can't get on a boat from a bridge, let alone change how the boat is designed or built or decorated. Also, bridges are not usually meant to regulate river circulation: what you describe is a lock, not a bridge. Nemo 20:00, 25 May 2016 (UTC)
 * This essay focuses on the collaboration between development teams and communities (wiki projects) as collective entities. These communities have hundreds, thousands of members each, and the majority of them might have opinions about boats but won't be willing or capable to jump in a boat and manipulate it themselves. Your scenario is about individual contributors volunteering directly in projects, which is a very important use case that the Technical Collaboration Guideline should address indeed. Collaboration with communities and collaboration with individual contributors cannot be addressed in the same way efficiently. The free software movement has many references about open collaboration between individuals in projects, but there are less references that can be directly applied to the very special situation of Wikimedia. This is why this essay focus on the latter.
 * Living in a region with many rivers, bridges, and locks, I still think that bridges are a better reference here. This is a guideline that aims to cover projects of all sizes and characteristics. Not all boats are expected to stop in every stage, and in fact none of them is required to stop. The analogy of this guideline indicates that if you skip checkpoints in the bridges you have a higher risk of finding surprises and being out of sync with communities as you approach the deployment phase.--Qgil-WMF (talk) 12:22, 26 May 2016 (UTC)

Silent majority
How does "silent majority" fit in the analogy? Is it a navigation term I missed? Nemo 20:02, 25 May 2016 (UTC)
 * This essay doesn't pose any creative competition to Aesop's Fables, indeed. If you don't understand what "silent majority" means in this essay, I can explain. If it's a matter of style, I welcome suggestions or we can move on.--Qgil-WMF (talk) 12:26, 26 May 2016 (UTC)
 * It's not a matter of style, I think the "silent majority" stop should just be removed. The boat should only sail towards destinations where it's welcome. Unprofitable visits are not something a boat should do. Nemo 13:22, 26 May 2016 (UTC)

Serious matters
"Blocking a project is a serious matter". This sentence should be balanced by an earlier sentence acknowledging that starting a project is a much more serious matter. The first day is the most important day for a boat, while stopovers are routine. Nemo 20:06, 25 May 2016 (UTC)
 * ✅ Good idea, thank you. Technical_Collaboration_Guideline/Vision.--Qgil-WMF (talk) 13:17, 26 May 2016 (UTC)
 * Thanks, looks better. Nemo 13:32, 26 May 2016 (UTC)

Project information
This is the most important section in my opinion, everything else is disputable. The basic information should be expanded, for instance most project ideas are doomed from the beginning because they lack a problem statement, goals and/or an overview of past discussions, ideas and approaches to the matter. Nemo 20:10, 25 May 2016 (UTC)