Wikimedia Product Guidance/Starting a project page

From MediaWiki.org
Jump to navigation Jump to search

A project page is a page on MediaWiki.org where you document what you will do.

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 item, then a project page would probably be beneficial.

Starting a project page[edit]

Start your project page on MediaWiki.org.[1] 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}} 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.[2]

Syntax highlight project page example.jpg
{{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?[3]

(More examples of questions frequently asked by community members can be found at Wikimedia Product Guidance/Common community questions.)

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. 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 15===, ===April 3=== 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.
  • For salient phases, please also add your updates to the Wikimedia Space; they don't have to be longer or different from what you are already posting on wiki, unless you want them to.

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. MediaWiki.org is where most technical documentation lives. Interactions with community members are easier on this wiki, as it features Structured Discussions (aka Flow) on talk pages, and the Code of Conduct applies to this technical space.
  2. Only the "name" and "group" parameters are required. More about the template: mw:Template:Wikimedia_engineering_project_information.
  3. 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.