Technical Collaboration Guidance/Milestone communication

Tracked in Phabricator
Task T131883

There is information to be shared between Wikimedia Foundation product teams and Wikimedia movement community members and end users. The purpose of this guide is to provide simple advice on when to communicate, where to communicate, and what to expect in return. This guide assumes that there is a general product team description page, a general page for a particular product, and a page for documenting communication milestones.

When and how edit

Products in development have milestones for information that can be shared with the Wikimedia communities. Information sharing builds knowledge and trust: the product teams share what they have with communities, and the communities share information that they have about the milestone with the product teams. Some examples of what can be considered milestones for information:

Software is being considered, and research and discussion is needed: check against principles, strategy, existing plans.
How the software works is being considered and decided: user interaction, the look and feel of the rest of the site
A roadmap, plan, or timeline is determined, including tentative release dates: major community or WMF initiatives that may compete for time and energy from volunteers

After the information is communicated, community members then have the opportunity to respond with questions, comments, and concerns that will help the product iterate.

Where edit

Information about a product's development can be communicated at least towards the primary audience of the team's focus, for example the team's talk page, public mailing list, or appropriate community forum. There are some concrete best practices about where to communicate milestone information:

Must-have: a dedicated wiki subpage of the product and/or project's page on mediawiki.org. The nutshell of the milestone information can be transcluded to the main page, with full text of the information on the subpage. The subpage also has the benefit of a discussion platform with the accompanying talk page.
Optional: Beta Features is an available option to get qualified software in front of end users for testing. All Beta Features offer direct links to leave feedback about a product.
Optional: a dedicated team or project mailing list. Ideally, this communication is a nutshell of what can be found on the wikipage. Further feedback can be directed to the talk page for centralization.
Optional: a subscription-based newsletter that can contain all the information needing to be shared, with a link to the relevant talk page for discussion.
Optional: mass-message delivery to appropriate community forums. Ideally, this communication is a nutshell of what can be found on the wikipage. Further feedback can be directed to the talk page for centralization.

What to say edit

Among the most important things to include in product proposals and updates are descriptions of the product (what?), estimated timelines (when?), who will be impacted (who?) and where this will take place (where?). It is also important to set expectations for feedback and replies that are being sought out: an open call for feedback is vague, and will leave the communities and product teams with little to work on together. Defined expectations in feedback allows for clearer goals and better understanding of purpose. Finally, remember that information is generally written for everyone, while replies are written towards an individual.

See /Draft

Proposals edit

Must-have: a clear objective for the project, feature, or product. What is the rationale for doing the work? It is important to define purpose and what practical outcomes are expected.
Must-have: a timeline for the project, feature, or product. Even if it is just a rough estimate, information should be provided on roughly when a community member can expect to see a project, feature, or product moving forward at various stages.
Must-have: clearly outlined expectations of what is being asked of community members. Ask specific, concrete questions.
Must-have: published documentation that researches user needs to support the proposal, as well as any past attempts at solving the same issue.

Updates edit

Must-have: immediately identify and explain changes that may have occurred with the project or project plan since the initial proposal or last update. Identifying and clarifying shifts in focus keeps everyone with the same expectations for the outcome.
Must-have: a timeline or dates for benchmarks, even if it is repetition of a previously published one.
Must-have: if pre-defined, outline clear expectations for feedback about the update.
Optional: an archive of messages distributed to community members and venues, if your project is long-term with a regular update cycle.

What to expect edit

Generally speaking, the primary goal of a Wikimedian's contributions to the projects is not testing software, so the response to calls to feedback may be limited to a small number of interested volunteers. Product teams can expect a few things from communities after issuing a request:

There isn't really an expected or average feedback response time or rate. If volunteers are interested enough to comment, they may leave useful feedback. This cannot always be expected, and silence should not be taken for apathy.
You'll hear from the users when software is deployed into production. Calls for feedback prior to release of a product may attract some attention, but there is no guarantee; however, if your product does not behave as expected when released, the users will let you know.
Users will likely respond with a lack of familiarity with the technology. This applies to both what the user expects from the software and what its actual intended behavior is, as well as a lack of technical lingo.

Translations edit

The Wikimedia movement serves a global audience and supports projects in nearly 300 languages. Having information available for volunteer translators to localize and disseminate is crucial to spreading important information about Wikimedia Foundation product and engineering work. Proposals and updates can be marked for translation followed by asking translators for assistance. This can create a network of users helping to spread information and gather feedback for products and projects. Additionally, there is a mailing list for volunteer technical ambassadors to gather information that needs distributing to communities.

Must-have: if a target audience is not English-speaking, translations should be made into the appropriate language (or languages) when feasible. Not all messages will be able to be translated into every appropriate language.
Must-have: if the target audience is international, English must remain simple, with short and understandable sentences to ease translations and to be understandable when no translations are provided.

Getting translations edit

Translations are primarily obtained through four ways: automated messaging on-wiki from marking a page from translation, emailing the translators' mailing list, one-to-one requests, or system messages translated through translatewiki.net. Of these four methods, generally speaking sending an email to the translators' mailing list or contacting an individual for a request are the most common way for anyone to ask for translations. Messaging through the translate extension requires a user right, and translatewiki.net is not a Wikimedia project.

Distributing translations edit

Announcements and calls for feedback are generally distributed through mailing lists as well as on-wiki. Unfortunately, major movement mailing lists are predominantly in English and do not support distributing translations very well, if at all. Additionally, far fewer people read mailing lists than the wikis. On-wiki messaging is the way to deliver new as well as updated information to the wider international audience of users.

Additional considerations edit

Provide space for translators to write their own version of the message. If there is information to be communicated, consider providing translators with all the information that they need to compose their own messages rather than direct translation. This gives a personal touch to the message, and allows for flexibility in language that might be difficult otherwise.
Provide context to translators, by defining a glossary of the main terms. That glossary will help translators to create accurate translations.
Reduce translation fatigue. Volunteers tire of translating a constant stream of communications and system messages. Requests translations only when necessary. Re-use the exact language of previous messages when possible.
Marking a page for translation makes the page more difficult to update. Consider providing updates that need translation in pieces, and create main information pages knowing that extensive updates to the page may create additional work for everyone due to how the translation extension works.
Long or complicated pages are difficult to translate. Make all messages that need translation as short and simple as possible for the information contained.