Research:Project documentation best practices

This page in a nutshell: This page describes best practices for documenting research projects on Meta.

Best practices for WMF researchers

There's no one canonical way to create a research page, but there are some steps that you should almost always take.

1. Go to the research project portal, click "+ project" and enter a descriptive title for your project: The title doesn't need to be perfect, just descriptive. If you're not happy with your initial title, you can move the page to a page with a new title, or create redirects from pages with alternate titles. Ask for help if you're unsure how to do this.

2. Add some relevant details about the project: Generally, the only information I add on the 'page creation' step is a few basic fields in the infobox: project status, contact (probably you!), collaborators, start month, and start year. For 'contact' and 'collaborators', paste in the investigator template (if more than one collaborator, separate templates by commas). So for example use |contact={{Investigator|[[User:Jmorgan (WMF)|Jonathan Morgan]]|Wikimedia Foundation}} for a contact/collaborator who has a Wikimedia user account and |collaborators={{Investigator|Lucas Dixon|Jigsaw}} for someone who doesn't have a Wikimedia user account. The 'status' parameter accepts 5 different values. By the time I'm creating a research page, I'm generally already planning to do the project, so I usually start with 'planned' and then change the status to 'active' once I've started to perform work on the project. This parameter adds a relevant tracking category to the project page.

3. Publish the page and add in basic information about the study: I generally start with a few sentences in the 'lead' section, and perhaps the 'methods' section. The 'Policy, Ethics, and Human Subjects Research' section is more for non-WMF researchers. Unless my research involves sharing non-public data outside WMF, or accessing novel sources of data, or using existing data in unexpected or controversial ways, I generally just add a generic statement like "This research will be conducted and data stored in accordance with Wikimedia's guidelines for informed consent and privacy, data access, and data retention." The 'timeline' section can be added at this point if you want. I often find my initial timeline projections to be inaccurate, but an estimate doesn't hurt :)

4. Include a link to a relevant Phabricator task to the top of the page: Use the tracked template. Here's an example. I also generally link back to the meta research page from the Phabricator task, for full transparency and easy navigation.

5. Fill in the open data and open source parameters as necessary: If you already know where your code and (public) data will be hosted, link to those repositories.

1. (optional) add the Wikimedia Research Project category to the bottom of the page: Since there are lots of non-WMF (and some WMF but not Research team) projects in the Research index, I created this category so that we have a single place to point to for all of the projects that are being led by or substantially contributed to by members of the Research team. Other researchers at WMF are welcome to use this category too, but so far it's primarily used on Research team projects.

2. (optional) add a 'Projects' section to your userpage on Meta. I noticed that Aaron had done this, so I copied him: ) This is a nice way to point to all of your projects from a single place. It will be extra useful once the Research Landing page is live, because profiles of Research team members on that microsite will link back to our MetaWiki User pages. Aaron's approach, which I adopted, is to put the project lists ('Active', 'Backburner', and 'Completed') onto a subpage of his userpage and then transclude that subpage under the 'Projects' heading on the parent page. I like this because it keeps things modular, but there's no problem with just listing the projects directly on your userpage.

1. As you make progress on your research project, update the page every so often with new information: You can add additional sections, subpages, or a work log (template) as desired.

2. When you're done with the project, fill in any missing information and update the status: Make sure you've linked to all the relevant project resources (code, data, slides, publications etc), add in the end data, and mark the status 'complete'.

Additional information needed