Wikimedia Product Guidance/Starting a project page

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?

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

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

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.

{{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

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

Background

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?

(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

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

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

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.
  • You may also set up your page so that the updates section being shown is actually transcluded from the updates subpage. For instance, updates in the box at this Commons portal are coming from the related subpage.

Help

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

Here are some examples of project pages to look at:

• Language: Content Translation V2
• Community Tech: Global preferences
• Editing: 2017 editor performance improvements
• Anti-Harassment Tools: Interaction Timeline