Wikimedia Engineering/Project documentation howto

The Wikimedia Foundation aims to work as transparently as possible, and this includes development and operations work (collectively referred to as "engineering").

Engineering projects are documented publicly whenever possible. In particular, development projects each get a "project page" on this wiki.

The project page is the central venue for the project team to coordinate their efforts publicly, and for the rest of the world to learn about what is being done and how they can help. MediaWiki development relies heavily on volunteers. Project pages allow you to make it easier for volunteers to find information about your projects, and to get involved.

Project pages usually include basic information about the project (name, description, team, dates, etc.) and links to other documents (design and architecture docs, etc.). It's really up to you and your team to find how to best use the project page. Just know that the more open you are, the more engaged the community will be about your work.

A very important piece of information for a project is its current status; status updates are recorded in a subpage and surfaced in many places, including the monthly engineering report.

This page provides information on how to create, use and update project documentation pages. Feedback and questions are appreciated on the talk page.

How to create a project page

1. If you're creating the project page from a red link on a team hub, skip to step 3.
2. Otherwise, enter the name of the project in the field below and press the button

   
   

3. Fill in the fields of the template according to the instructions, and save the page. This will add more boilerplate content.
4. If appropriate, remove the unneeded elements on the page, and add links / content specific to your project

How to create the status subpage

Status updates are recorded in a subpage of each project page. When a project page is created with the box above, it contains a red link to the status subpage. You can copy/paste the content below to initialize the page (and edit the date & content). Dates are in ISO 8601 format.

Last update on: <section begin=latest />2011-12-31<section end=latest />

== 2011-12-31 ==

<section begin=2011-12-31 />Add your first status update here<section end=2011-12-31 />

How to add links to your project page in all the right places

The beauty of the Wikimedia engineering project pages and templates is that information is centralized on or around project pages, and it can invoked and/or displayed in many different ways and places.

Here's where you should invoke your project page, and which template to use (you can also just use the same template as the other projects on the page you're editing, and simply replace the name of the project page)

• All projects:
  • the Wikimedia Engineering portal — Syntax: {{Wikimedia project shortdesc|Project page}} (in the appropriate section)
  • the next monthly engineering report — Syntax: {{Wikimedia engineering report project status|Project page|date=2012-01-31}} (in the appropriate section), where the date is the last day of the month the report covers, in ISO 8601 format.
• For groups with a team hub — Add {{Wikimedia project index line|Project page}} to the appropriate section of the Features team hub, the Platform team hub or the Mobile & special projects team hub.

How to add a new status update to a project

There are three ways to add a new status update to a project with a project page. All three consist of editing the status subpage, from different places.

• For groups with a team hub — Go to your team hub (Features hub, Platform hub or Mobile & special projects hub.), find the line for your project, click [add new] on the right, check the date, and add your status update.
• Use the button — Go to the project page, click the "Add a new status update for this project" button, check the date, and add your status update.
• Edit the status subpage directly — Go to the project page, then to the status subpage, edit it using the previous status updates as a model.

In all cases, you might want to update the latest section at the top of the page; if you don't, your modifications won't immediately appear on the team hubs, but someone (probably Guillaume) will fix it shortly.

The status update doesn't show on the engineering report

For projects with a project page, the engineering report automatically invokes the status update from the last day of the month the report covers (in ISO 8601 format). You probably added the status update before that date, so it doesn't show.

Either fix the date of your status update to use the last day of the month (if close enough to the date), or the person assembling the report will fix it for you.

How to add a new status update to a project without a project page

Just edit the next monthly engineering report directly.

How to edit the project information (team, dates, etc.)

There are two ways to edit the project information.

• For groups with a team hub — Go to your team hub (Features hub, Platform hub or or the Mobile & special projects hub.), find the line for your project, click [edit info] on the right, edit and save.
• Edit the project page directly — Go to the project page, edit and save.

It's basically the same thing, except if you use the link from the team hub, you only see the first section of the page (i.e. what you actually want to edit), and not the whole thing.

This is too complicated / It doesn't work

Don't overthink it. There's a limit to what templates and parser functions can do, which means the system is fragile. Just add the information and someone will clean it up.

How to do something that isn't listed here

1. Be bold.
2. If everything else fails, ask Guillaume.

See also

• Wikimedia engineering report/How to — Guide to writing and publishing the monthly engineering report.