Wikimedia Product Guidance/All-in-one

From mediawiki.org

Engaging communities in the development and deployment of new software is an essential aspect of Wikimedia Foundation work. This guide aims to support Wikimedia Foundation Product Managers and others in related roles to effectively foster community participation. Created in 2019 by the Audiences (currently: Product and Technology) and Community Relations (currently: Movement Communications) teams, it summarizes years of experience and best practices. Its sections provide a checklist of the characteristics our products should have, and explore how to choose an audience, where to post product news and updates, and how to involve and seek feedback from the communities throughout the software development process.

Using these methods, the Wikimedia Foundation works to collectively build tools that support the people behind the Wikimedia projects. We hope this content proves useful, both to those involved in carrying out these responsibilities and to those looking to understand the processes we use. We hope it sheds some light on how the Wikimedia Foundation and diverse Wikimedia communities can best work together to toward the shared goal of spreading free knowledge around the globe.

Product Principles[edit]

Purpose[edit]

The Wikimedia Foundation designs and develops software so that people can further the movement's mission: to empower and engage individuals around the world to collect and develop educational content under a free license, and to disseminate it effectively and globally.

These shared Product Principles define the kind of products and experiences that we aspire to build.

Wikimedia Products should be...[edit]

  1. Community-centric: enabling welcoming, vibrant communities where new and experienced people come together to create, share, and discover knowledge through collaboration.
  2. Usable for all: promoting equity through usable, useful, and inclusive tools and services that meet the needs of a wide range of people and machines across user experiences.
  3. Intentionally transparent: demystifying the knowledge creation process and encouraging participation by giving everyone visibility into how information is created, verified, and improved over time.
  4. Extensible and sustainable: creating the conditions for people and machines to use, reuse, and build on top of our platform, extending free knowledge and supporting a sustainable future for Wikimedia.

Why these Principles?[edit]

Wikimedia is a place, not a database: We believe that Wikimedia is and must remain a vibrant place on the internet. Welcoming spaces are vital to the work of building and maintaining the wikis. Providing readers a place to consume and engage with free information is more indispensable than ever. So, we must build tools that promote collaboration and support vibrant knowledge communities.

Usability is an equity issue: These principles also rest on the notion that free software isn’t free unless it’s usable. We seek to make Wikimedia software usable and useful for people and machines. We will break down the software barriers that prevent participation while giving users the tools to customize their experience. In short, we will “make the simple things easy, and the hard things possible” for as many people as we can.

We must serve more than just facts: Finally, these principles rest on the movement strategy's assessment that we play a vital but poorly understood role in the knowledge ecosystem. Our products will make knowledge literacy a part of everyone’s experience of Wikimedia, exposing people to how information is created, verified, and improved, and encouraging civil participation in the process.

Process[edit]

See Product Principles/Process.

Starting a project page[edit]

A project page is a page on MediaWiki.org where you document what you will do. As a rule of thumb:

  • MediaWiki.org is where most technical documentation lives. This is developers and techies' happy place :) You can see an example at Growth/Feature summary. Extensions even have their own namespace here! (example: Extension:Thanks). Interactions with community members are possible on this wiki: it features Structured Discussions (aka Flow) on talk pages, and the Technical Code of Conduct applies to this space, but most importantly, you will be able to mark a page for translation here.
  • The Technology department uses wikitech.org for documentation about production clusters, Wikimedia Cloud Services, Toolforge hosting, and the Beta Cluster. While it may work for them, it has significant limitations related to community engagement - it needs a separate login as Wikipedia credentials don't work there, it can't be edited anonymously and it doesn't allow for translations.
  • You also should not need to use Meta-Wiki for your project. It has a non-technical focus (although you may need to publish research projects and results there: example, m:Research:“Newcomer Experience” pilot project - Advancement Email campaigns). However, nothing stops you from creating a redirect from Meta-Wiki to MediaWiki.org if you think that is essential for the discoverability of your project. This explanation also applies to Wikidata.

Which projects need project pages?[edit]

Projects come in many sizes, from extremely large projects (like creating an online encyclopedia) to very small projects (like adding a few characters to an interface message). So, which projects benefit from a project page?

For large projects, for example a project like "improve new editor retention", a description of the project should have been included in the annual plan, so creating another project page could be duplicative. For small projects, the project might be so small that the entire description and rationale is concisely summarised in a single Phabricator task, and you might spend more time writing a project page than it takes to complete the project itself. Neither of these situations are an efficient use of resources. There is also the risk of interested users tuning out if there are hundreds of project pages.

A rule of thumb is that if your project represents roughly a quarter of work (that is, three months), or is a response to request such as a Community Wishlist Survey proposal, then a project page would probably be beneficial.

Starting a project page[edit]

Start your project page on MediaWiki.org. This is where people will get all the basic information about your project. Everything else will go in subpages, easily accessible from this "home." Or, perhaps your project is part of a larger project, in which case the page you're creating will be one of the subpages. A good title would look something like https://www.mediawiki.org/wiki/Your_team_name/Your_project_title.

This page will have a talk page that is the main, centralized venue for community members to ask you questions and provide feedback. In the first section, invite people to put this page on their watchlist, so they can watch for updates. You can use the {{Add to watchlist }} button to encourage people to watch your project page.

Because your product page will be on a wiki, most users will be aware that content can be a draft or a work in progress. However, if you want to be clearer about that, you can add the {{Draft/core }} template to the page.

Creating an infobox[edit]

If you want, you may copy and paste code to generate a nice little box on the right side of the page with the basic info for your project.[1] 

{{Wikimedia engineering project information
| name        = Syntax highlighting
| description = Wikitext syntax highlighting in 2010 and 2017 editor
| start       = 
| end         = 
| group       = [[Community Tech]]
| lead        = [[User:Niharika|Niharika Kohli]] (product owner)
| team        = [[User:DannyH (WMF)|Danny Horn]], [[User:Kaldari|Ryan Kaldari]], [[User:MusikAnimal (WMF)|Leon Ziemba]], [[User:MaxSem|Max Semenik]], [[User:SWilson (WMF)|Sam Wilson]]
| Phabricator = community-tech-sprint
| updates = [[meta:Community Tech/Syntax highlighting#Status|Status updates]]
| progress = [[meta:Community Tech/Syntax highlighting|Progress reports]]
| previous    = 
| next        = 
| projectpage =
| display     = {{{display|}}}
}}

Adding sections to the page[edit]

To keep project pages in a somewhat standardised format, the format of the page is recommended to use the following sections:

Background[edit]

Add a ==Background== section to provide context and get ahead of common community questions. For ideas about what goes into this section, you could answer questions such as:

  • What are the goals of the project? It's important to define purpose and what practical outcomes are expected.
  • What research is it built upon?
  • Were there previous attempts at fixing the same problem? What happened to those?[2]

(More examples of questions frequently asked by community members can be found at Wikimedia Product Guidance/Common community questions. In some cases it may be wise to write a separate FAQ page - see Growth's example.)

What is changing[edit]

Add a ==What is changing== section.

  • Describe the change in plain language. Keep in mind that all content should be translatable into other languages (so don't forget to mark the entire page for translation). Use short, simple, direct sentences.
  • State who is going to be affected, and where. For example: will every user in our environment be affected, or will your project target a specific group of users or wikis?
  • Provide examples, screenshots, wireframes, everything you have to help people understand your work and give feedback about it.
  • Can people opt out of this change for themselves, if they wish? If so, explain how.

Feedback[edit]

Add a section about ==Feedback==.

  • In general, you should be open to receiving any kind of feedback. More incoming information is good for the project.
  • When there's a specific open question that you want feedback on, make it clear. Are you asking people to help you pick between two alternatives? Do you want to brainstorm solutions to a problem?
  • Point to the feedback page as the venue to collect feedback: if you are asking multiple questions, you can create in advance specific threads in the talk page and then point to each of those separately. When you need more feedback venues, you can explore other options.
  • Don't forget to watchlist your own project page! ;) Community members deeply appreciate seeing PMs and designers engage in threads about product specifics, feature requests, etc.
  • Once the project page is created, announce it on relevant communication channels.

Status updates[edit]

Add a ==Status updates== section.

  • Update the page regularly with concise status updates, especially if there's a new decision, a new mockup or a new problem that you're trying to solve.
  • Add subheadings: ===March 2022===, ===April 2021=== so that people can follow the ideas as they develop. This is essentially a mini-blog about the project.
  • Post when something interesting happens (a decision about a front-end change, new wireframe/mockup, new version for testing...) or once a week/month, whichever comes first.
  • For major projects (i.e., multiple years of work, or massive community feedback expected), please consider having status updates on a subpage instead. The Growth team, for instance, maintains a single updates page covering all the work they do.

Help[edit]

Users will need documentation about how to use your new product. Typically this is done by creating a subpage (example: mw:Help:Extension:ContentTranslation) and prominently linking to it from your project page. Add a ==Help== section to the page and add the link to the subpage there.

  • A help page features instructions, screenshots, magic words that automatically render interface messages for your product in the user's language, examples, exceptions... anything that can help the user navigate your creation.
  • For very small projects/features, that require a few lines to explain how it all works, you may consider keeping this information directly on the project page.
  • It is okay if users "fork" documentation from mediawiki.org to develop content on local wikis, but the practice shouldn't be encouraged. Local docs end up being unmaintained very quickly, even on bigger wikis. Centralised docs, on the other hand, allow for translation and serve a much larger and global audience, not just Wikipedia users.

Examples[edit]

Here are some examples of project pages to look at:

Footnotes[edit]

  1. ↑ Only the "name" and "group" parameters are required. More about the template: mw:Template:Wikimedia_engineering_project_information.
  2. ↑ Publish documentation that researches user needs to support the proposal, as well as any past attempts at solving the same issue. Wikimedians will ask you for data, and will want to see that you are not reinventing the wheel. If your work is based upon a request from community members, then say that explicitly.

Communication channels[edit]

Knowing where to ask for feedback or to post your message is tough. Do you do it on a private wiki or mailing list? Do you do it in public on Meta or on a project's village pump? Or do you have a graduated strategy, where you float it on a small, private forum first (this wiki, for example), then start asking for more feedback in more public places?

There are no hard-and-fast rules. In general, if you're stuck on "Where should I post my announcement?" or "Where do I find the people I'm looking for?" try thinking in these terms:

  • Who is your target audience? (not everyone in our movement will need to know or take action about your thing, right? Do you need the attention of the techies? Of affiliates? Of editors from a certain project or with a specific workflow?)
  • When do you need to notify the audience and how often? (Immediately? Just once? Or do you need people to see the same message daily until a certain date?)
  • What is the content of the communication? (is this an emergency or a routine thing? is it a polite FYI or a call to arms?)

Once you've answered these questions, you can choose a channel from the channels menu.

The Movement Communications team is happy to advise Product Managers on which channels may work best for each project.

Sharing your product information[edit]

Information about a product's development can be communicated through several channels, such as the team's talk page, a public mailing list, or the most appropriate community forum. There are some concrete best practices about where to communicate milestone information:

  1. A project page with status updates section or subpage, per Wikimedia Product Guidance/Starting a project page.
  2. 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.
  3. 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.
  4. 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.
  5. Optional: mass-message delivery to appropriate types of contributors or community forums. As with the team or project mailing list, this communication is a nutshell of what's on the wikipage, and further feedback can be directed to the talk page for centralization.

Finding pages where people congregate: village pumps and co.[edit]

If you need to make announcements or to talk to community members, then you need to find the right pages for that.

Large wikis may have multiple or specialized pages for making announcements and talking. Smaller wikis might have one—or none. Look for:

  • Village pump pages: these pages are explicitly for talking to other people in the community. Wikidata has a list of all local village pump equivalents (their names vary between communities). Some big wikis have multiple village pumps, each of them hosting different contents (one is for getting technical help, one is for off-topic chatting, etc.). Most village pumps at very small wikis look like a long page filled with mass-delivered messages in English.
  • Community boards: these pages are for making more formal announcements. Some may collect information such as project milestones or work that needs to be done.
  • Embassy pages: these pages are for people who don't speak the local language. As for any other page, a response may not be guaranteed. List on Wikidata.
  • Administrators' noticeboards: these pages are specifically for announcements or requests that require attention from a sysop (admin). In several cases, you will need to copy and paste a template to state what you need from them. List on Wikidata.
  • WikiProjects: on a few larger projects, subgroups of editors have pages to discuss specific topics. If you need to reach subject-specific people, these are a good option. List on Wikidata.
  • Check the {{welcome}} templates for links to help or discussion forums. On some wikis, community members will put such a template on your talk page after your first edits (in some cases, a bot will do that: sometimes you can even receive the message seconds after just visiting any page on that project). List on Wikidata.
  • If all else fails, the talk page for the Main Page. List on Wikidata.

Using interlanguage links[edit]

If you know what kind of page you are looking for on one wiki, you can use it to find similar pages on other languages for that same project. This works for content pages as well as discussion pages behind the scenes. Interlanguage links are usually listed on the left-hand side of the screen, just below the "Toolbox" and next to the gear-shaped icon for the Universal Language Selector. The links are written in the language that they represent, e.g., "Français" rather than "French". They may be alphabetized by the projects' language codes, so that, for example, Basque (eu) comes before Persian (fa), which comes before French (fr). On some wikis, the order depends on your previous selections, or on other factors. While the options appear in the local language, they are all searchable in English, so if you want to find the Arabic village pump equivalent, you can type in "Arabic" in English without having to first find a translation.

To use this feature, go to a page that you think is the right target at a project that you are familiar with. For example, to leave a message of general interest, you might go to the main village pump page on the English Wikipedia. When you look in the sidebar on the left, you will find the Language menu, which provides links to the equivalent page on almost 200 other Wikipedias. These are reciprocal links, so all village pump pages, regardless of language, should have the same list.

This feature only works within the same type of project. You can use interlanguage links on one Wikipedia to find similar pages on other Wikipedias, but you can't use them to find similar pages on Commons, Wiktionary, or other projects. However, many projects are structured similarly, and especially the English-language editions often have redirects set up from familiar pages. As a result, if you go to the English Wiktionary and search in "Help and project pages" for "Village pump", then you will find that Wiktionary:Village pump redirects you to the English Wiktionary's equivalent, which is Wiktionary:Beer parlour, and that this page offers interlanguage links to similar pages in other language editions of Wiktionary.

Luckily, you can now reach the equivalent of a given page in any language and in any project thanks to Wikidata. At the bottom of the list of links in the left sidebar, click on the pencil icon which says "Edit links": you'll be redirected to a comprehensive Wikidata page. As an example, see the Wikidata page that provides links to the main village pumps on most WMF wikis.

Using off-wiki communication channels[edit]

Some communities congregate mostly off-wiki, so it's important to be familiar with these channels as well. See Community Engagement's guide to off-wiki communication channels.

Reaching out to key stakeholders[edit]

When you're looking for feedback or action that goes beyond a few wikis, there are some recommended groups and venues you may be interested in:

How to add noteworthy items to Tech News[edit]

How to make a newsletter[edit]

How to create a newsletter via Extension:Newsletter[edit]

  • If your audience lives on mediawiki.org, you can also create a publication via the mw:Extension:Newsletter. This is still an experimental service.

Mass message systems[edit]

Use the MassMessage system to automatically deliver your note to a list of pages or people; there is a list of people who are able to send a message on your behalf if you don't have the necessary user rights. Distribution list/Global message delivery is the basic list for central community pages on all projects, but anyone can create specialized lists to reach only the most relevant targets.

If you need a response, or if there is any possibility that people will have further questions, then include a link back to a central location of your choice (generally, a page on Meta for policy questions or a page on MediaWiki.org for technical issues). If you are posting to message boards like the village pumps, then you need to include a date stamp at the end of the message.

Be careful with MassMessage: it is easy to spam the wrong list of people, or forget to close an HTML tag that breaks hundreds of pages across wikis that you'll need to go through and fix manually. In some cases, your message may be labelled as "spam" and treated as such. Try to pre-empt these issues by talking to an expert; members of the Movement Communications team are happy to help you avoid these pitfalls. With great power can come great messes.

If you need to deliver messages at mediawiki.org, you may want to know that the correct syntax in the Target template is site = www.mediawiki.org.

There's also a distribution list for Technical Village Pumps, and a Wikidata MassMessage tool that "generates a list of wikipages based on Wikidata items, ready and formatted as a delivery list for MassMessage".

In several cases, the advice provided below applies also if you want to distribute messages manually instead.

How to make your message readable[edit]

LTR & RTL[edit]

Even if your message is in English, you need to label it so that it will be readable on a non-English wiki. Put your message inside the following HTML tag: 

<div lang="en" dir="ltr" class="mw-content-ltr">
Your important notification.
</div>

This will ensure that the message is treated as English and left-to-right by the software. If you do not do this, then your message may be displayed with all the letters running in the wrong direction on the page, or it may break the formatting for the rest of the page. Mastering the use of these tags will make you look considerate!

If the message is in English[edit]

Use some translated messages to begin a message when you post in English on a wiki that is not in English (that means, virtually everywhere!)

  • {{int|Hello}} will display "Hello" in the language that each user specified in their preferences.
  • {{int|Please-translate}} will display "Please help translate to your language" in the same way.
  • {{int|Feedback-thanks-title}} will display "Thank you!" in the same way. (NB: {{int|Thank-you}} also exists, although it may have fewer translations as it's a more recent message. This needs verification.)

For example, if nobody has pre-translated your MassMessage into Estonian before you send it, then you can add: 

{{int|please-translate}}

Feedback wanted on mobile web contribution prototype

The [[mw:Special:MyLanguage/Reading/Web|Web web]] team is working on improving the [...]

{{int|Feedback-thanks-title}} [[m:User:Foo (WMF)|Foo]] ~~~~~

Will be displayed to a reader using a Estonian preference/wiki like this:

Palun aita emakeelde tĂľlkida
Feedback wanted on mobile web contribution prototype
The Web team is working on improving the [...]
Aitäh! [your signature]

Write short, simple sentences. This helps translators, English language learners, and people who rely on machine translation. Tools like readability indicators, the Hemingway app, the SimpleWriter and the Up-Goer 6 check for complex and rare words. The website SimplyPut.ie gathers useful resources on how to write in plain English and provides a handy list of words and phrases to avoid.

If you plan to work with Tech/Ambassadors, you can create a translatable page with your message in English. This way, it will be easier for Ambassadors to spread the word, by using the translation extension; if you wrap the page (except for the "languages" tag) in ‎<pre> tags, they'll be able to just copy/paste everything. This is how the example above, with the grey background, has been made.

Other advice[edit]

  • If your message discusses elements in the user interface ("Click on the 'Edit' button"), then try using the qqx trick to provide automatic translation of the names of buttons and other system messages.
  • Avoid using any templates in your message. Most templates, even common ones like {{@}}, are not present at smaller wikis.
  • Don't use the usual 4 tildes (~~~~) to sign messages sent through MassMessage. That will result in your message being signed by an account named "Mass Message Delivery system", instead of by you. Instead, type your name manually, that is, by linking to your userpage on Meta or another wiki, and use five tildes to set the date: 
    [[m:user:Trizek (WMF)|Trizek (WMF)]] ~~~~~

Examples[edit]

  • On Office wiki, look for "codfw" to see the communications plan, written and executed by Movement Communications, to communicate about the switchover to Dallas backup datacenter (and related planned outages) in 2017. It identifies audiences, defines which steps to take at which point in time, and who does what in the process. Having a plan doesn't simply make things smoother; most importantly, it can be reused with minimal adjustment and learning curve.

Additional resources[edit]

Common community questions[edit]

FAQ from the communities[edit]

This page lists questions that community members routinely ask when they learn about a new, upcoming project. It is not meant to be comprehensive—Movement Communications have read these questions often enough that they have decided to try and summarise the most frequent ones. You can use them to draft your own FAQ page.

Question Rationale: why does this matter?
Background
What problem(s) is this intended to solve, and for whom? This helps people identify if they will be affected, which may influence how much attention they pay, and the nature of their reaction.
Based on what evidence, research, or request? Wikimedians prefer to not only hear about research results, but to read it themselves. Some of them may even be able to point out additional prior research. A planned software change may not make sense to a user or set of users, based on their experience. Providing research may help the users to see the problem from a different angle, or provide additional input.
Has this been tried before, internally (by staff or community members), or externally (is it an industry standard)? Previous efforts, if they exist, presumably inform current plans. It's good to know what lessons have been learned. Additionally, people might have preconceived notions of expected software behavior from other sites. We also try to avoid proliferation of standards.
What is changing
Will this replace an existing tool? Replacing an existing tool is a dramatic shift for people, and takes more work to get used to. Many of the workflows for curating the content on many "major" wikis are highly customized, and prone to break easily. Editors need time and space to adjust to changes to their workflow(s).
Will this break anyone's workflow? To a significant extent? If you are affecting people who are not your target, can precautions be taken to not do so? The extent to which workflows will (or might) break is important in determining the amount of communication necessary for a change. If people who are not directly benefiting from software are affected by a change, they tend to be adverse towards the change. Minimizing this risk is important to acceptance.
Will it add to existing contributors' workload, if it's a success? The extent to which workloads are increased is important when communicating about a change. The communities will be more open to adjusting if they sense that drawbacks aren't being hidden, but that they have been foreseen and that measures have been taken to mitigate issues.
Will it scale? (both to small wikis, and to large wikis) People want to know if they can or should expect to see this on other wikis, or affecting millions of users.
Have you defined a glossary introducing any new terms? Glossaries help native-language speakers understand new terms, and helps translators to introduce new terms into their language communities as well.
Timeline
Do you have a timeline, no matter how rough? People would like to know when to expect things for various reasons such as event planning, and a rough idea of when things may happen will help relieve some anxiety about potential changes. If yes, make sure it is published. If no, at least publish an idea of when one might be available.
Can you define, even roughly, the product's individual definition of alpha/beta/MVP/release? People want to know the definition of a product's stage, so there are parameters and boundaries around the development limitations. People can tolerate more bugs and missing features if the status of the software and the state of its iteration is clear.
Feedback
Where are you discussing this with the communities? Discussion is the basis for many decisions on-wiki. Communities often prefer to discuss software changes before they occur, identify blockers, concerns, bugs, missing features, support, assistance in communications, etc. Documenting the location(s) makes it easier to both centralize new discussions, and to find old discussions.

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, and assistance can then be requested directly from translators. 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.

There are two types of translations:

  • full text translations, alias Translating documentation or communications
  • interface translations

Getting translations[edit]

Translations are primarily obtained in 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, sending an email to the translators' mailing list or contacting an individual for a request are generally the most common way to ask for translations. Messaging through the translate extension requires a user right, and translatewiki.net is not a Wikimedia project.

Translating documentation or communications[edit]

Principles[edit]

  • 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.
  • If the target audience is international, the English must remain simple with short and understandable sentences, both to facilitate translation and reach as many non-native English speakers as possible when no translations are provided. Wikimedians are rather culturally sensitive and they tend to dislike messaging that sounds too "US-centric", for example (overuse of positive superlatives), so this is something to bear in mind and account for.

How to create pages or messages that can be translated[edit]

Video tutorial on how to use the translate extension; you may also check out a Wikimedia Hackathon 2018 class on the subject.

Considerations about these translations[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 limiting them to a direct translation. This gives a personal touch to the message, ensures that the meaning is correctly conveyed, 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. Request 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.

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.

Translating interfaces[edit]

About Translatewiki[edit]

Translatewiki.net is a separate wiki. It is designed for translating the user interface—i.e. the buttons that say "Edit" or "History", the error messages you see if something doesn't work—not for policy pages or messages that you want to post. However, it is also a useful place for finding people who might be willing to translate other documents for you.

Translatewiki.net is not run by the Wikimedia Foundation, but some staff have major involvement in it (such as Niklas from the Language team). Wikimedia SULs do not work there, so all users, including Foundation staff members, have to register a new account and apply for permissions before they can work on translations. It can take some time for new account requests to be processed, so requests need to be made as early as possible. For some work, it may be more efficient to ask someone who already has an approved account. See the FAQ for more information.

  • Check Translatewiki
  • http://translatewiki.net/wiki/Category:User_languages
  • https://translatewiki.net/wiki/Special:SupportedLanguages lists languages and shows activity levels of translators at a glance. Click on the language you need in the word cloud, or scroll down the page, to get a list of all translators who have done work in that language. The color coding shows how recently the translator has been active (green = good, red=more than six months ago). Being inactive at Translatewiki doesn't mean that the person is inactive in their community. Many translators use the same name on Wikimedia Foundation projects as they do at Translatewiki.net, and you may be able to reach an "inactive" translator by looking for the user in the Wikimedia projects.
  • https://www.mediawiki.org/w/index.php?title=Special:Translate&taction=export You can select the group of messages and the language you are interested in to find out who worked on them before. Then click "Export for off-line translation" and "Fetch". A .po document will appear (you can open it in your browser or in a text editor). Users you are looking for are called Authors at the beginning of that document.

See also[edit]

Community involvement[edit]

The Wikimedia Foundation understands that community involvement in the design and development process is paramount to fulfilling our mission to provide essential infrastructure for the wiki projects. Foundation Product teams intend to be collaborative and receptive to feedback throughout the life cycle of a product.

Early feedback[edit]

Foundation Product teams should collaborate and share information with the communities about software features considered, as early as possible in the project timeline. The communication of proposals can include goals, plans, early designs and other information.

Community members may provide feedback about specific products and features from their early stages, through the communication channels supported by the project. Ideally, problems that have the potential to block further development will be identified at that stage, but sometimes concerns will not surface until the development phase.

A "blocker" is a bug, missing feature, or other problem that the development team decides should temporarily block deployment at some or all wikis. Communities are invited to submit bug reports and other concerns that they have, so that the development team can determine whether those problems should affect the deployment plans. A proposed blocker can have a big effect on a project, even if the proposed blocker has questionable relevance or legitimacy. Therefore, in order for a proposed blocker to be considered as possibly changing the course of a software project, it should:

  • be filed in the related Wikimedia Phabricator project or MediaWiki.org project page, and be identified explicitly as a proposed blocker, to distinguish it from other bugs or feature requests.
  • be consistent with the bigger picture: Wikimedia's mission, principles, strategy, annual plans, supported technologies, etc.
  • demonstrate familiarity with the project plan and actual use of the feature when available.
  • be actionable, e.g., "It doesn't work on this device" or "This product doesn't support oversight functions", rather than "I just don't like it" or "I think this product is a waste of money".
  • use constructive arguments, data, actionable alternatives, and collegial tone.
  • provide proof of a community consensus when speaking in the name of a community.
  • take prior discussions and agreements into account. There must be very good reasons to re-open a settled topic.

The same quality criteria are expected from the developers or other contributors disagreeing with these proposed blockers.

Ultimately, the final decision about whether each proposed blocker should actually block development or deployment belongs to the development team, not to communities.

Deployment on individual wikis[edit]

During the development cycle, there is a point when features are released to targeted users. When a feature is being released to the wikis through publicly documented deployment waves, communities can influence the best timing for the deployment of a product or major feature in individual wikis:

  • Communities pleased with a new feature or product can request to be included in the first waves, after showing proof of interest in their community discussion channel.
  • Communities with specific concerns or internal discussion can request to have the deployment to their wikis delayed to a later wave by following the process outlined below.
  • Communities with no strong opinions will be scheduled by the development teams.

It may happen that one or just a few communities will keep pushing back a new product or feature, while all the rest are satisfied with it. The likely scenarios are that either the new product or feature will keep spreading until reaching full coverage, or the community's concerns will ultimately persuade the development team to change the product plans.

In order to delay the deployment of a new product or feature in an individual wiki, the local community must provide a link to a community discussion and the list of actionable bugs, missing features, or other problems that they would like the development team to consider for "blocker" status. (Ideally, all proposed blockers are tasks filed in Phabricator.)

Development teams participate in the discussion about the proposed blockers to determine whether they are sensible, consistent with the project, actionable, realistic, etc. If the development team decides that none of the proposed blockers should delay deployment, then the deployment will proceed. If the development team decides that some or all the proposed blockers should delay deployment, and then addresses those proposals, the community will be asked for a new review. If no surprises are found, the deployment will proceed.

Some software deployments and most software removals are mandatory. Some deployments, such as offering a new API, cannot be handled as successive waves of deployments over time (instead, these deployments happen everywhere at once). In those cases, local communities will not be able to influence the timing.

Local configurations[edit]

Some local configurations can only be set server-side, usually by Foundation development teams. In some cases, separate configurations can be set for logged-in users and anonymous users. Generally speaking, core community members can represent their own interests well, while development teams can bring data and analysis about readers and other contributors.

Given these circumstances, communities should have a chance to discuss these local configurations, in these terms:

  • Communities have priority for defining the first configuration to be tested for features primarily affecting experienced contributors.
  • Wikimedia Foundation teams have priority for defining the first configuration to be tested for features primarily affecting readers and new contributors.
  • Goals and data gathered need to be included in the release plan, and the data gathered needs to be shared (unless there are privacy concerns, which should be explained in the release plan).
  • If an initial configuration is not producing the expected results, the development teams can test alternatives before they settle on a stable configuration.
  • Ultimately, the responsibility for defining product configurations belongs to the Wikimedia Foundation.

Thank people[edit]

Volunteer time is a scarce and precious resource. Thank people for constructive feedback, even if you ultimately disagree with their advice. If an individual volunteer contributes significantly to your project, be sure to acknowledge their contributions, just like you would acknowledge a similar contribution from a fellow staff member who worked in another team. The Language team does this consistently by including acknowledgments and highlighting volunteer contributions in bold in their monthly reports (example).

Communication roles and responsibilities[edit]

The goal of this page is to make a list of the most common public-facing tasks that teams need to perform, and to get agreement on "who does what". These tasks can be performed by both Product Managers (PM) and Movement Communications (MC); each team needs to figure out their own balance. The straw dog assignments below are based on a balance between current thinking and historical conventions. Some of the tasks may end up being a shared responsibility.

  • Create a project page for every user-facing project, with the intention of creating an open communication channel between the product team and the community. (PM)
  • Post early ideas including goals, wireframes, mockups, design planning docs and the results of user testing, in collaboration with designers and researchers. (PM)
  • Post status updates on the project page on a regular basis (at least once every 2 weeks), to keep people informed on progress and to encourage users to watchlist the page for updates. (PM by default; in agreed cases, MC with content produced by PM)
  • Make announcements on village pumps, mailing lists, Diff and Phabricator at appropriate times during the project -- kickoff of the project, posting a key update that needs feedback, a call to action for testing prototypes. (MC)
  • Identify mid-project opportunities for feedback, especially when there's a judgment call that community members can participate in. (MC)
  • Watch discussion on project talk page and respond within reasonable timeframe. (MC/PM)
  • Watch discussion on extension talk page and respond within reasonable timeframe. (Tech Lead)
  • Watch discussion in other places and respond within reasonable timeframe. (MC)
  • Surface questions and ideas to the product team for discussion. (PM/MC)
  • Triaging bug reports, reproducing problems, creating Phab tickets. (QA when available, others)
Retrieved from "https://www.mediawiki.org/w/index.php?title=Wikimedia_Product_Guidance/All-in-one&oldid=5572039"