Technical Collaboration Guidance/Milestone communication
|This page is currently a draft.
More information and discussion about changes to this draft on the talk page.
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
Products that are being developed 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, and the communities share information about the milestone back. 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, look and feel to 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.
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 had into the appropriate language or languages as possible. 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 or to be understandable when no translations are provided.
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, and 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, and further feedback can be directed to the talk page for centralization.
What to say
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.
- 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.
- Must-have: published documentation that researches user needs to support the proposal, as well as any past attempts at solving the same issue.
- 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 predefined, outline clear expectations from 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
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 and volunteers cannot be forced into testing anything. 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 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 little guarantee; however, if your product does not behave as expected when released the users will let you know.
- Users will likely respond with 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.