Outreachy/Round 19/MediaWiki documentation improvements project guidelines

Overview[edit]

We're working on improving the MediaWiki Action API documentation pages, 20 pages at a time. This guide is to help new contributors get started.

Basics[edit]

Before you begin, make sure to read the project description, resources listed in the project description, and the MediaWiki Action API to clearly understand the context of this project.

Verify that you have the following set up:

Next step[edit]

Select an API page[edit]

The Phabricator task description contains a list of Action API pages (microtasks) that you can work on. From the list, choose an Action API page and add your name in the 'Work in progress' column.

To do so:

Make sure that you're logged in to Phabricator.
'Subscribe' to the task.
Click on the 'Edit task' option and add your name next to the selected page.

Note:

The Subscribe and Edit task options are available on the right-side on desktop view and in the hamburger menu on the top-right on mobile/tablet view.
Select only one page in the beginning. You can work on a different page after your improvements have been reviewed and merged.
If all microtasks have been claimed, please inform the mentors (@jeropbrenda) on Zulip, new microtasks will be added soon. In the meantime, you can look into contributing to other open Phabricator tasks. See the 5th point here: #When you're done.

Create a sandbox page[edit]

Avoid making changes to the API pages directly. Instead, create a page in your Sandbox by replacing username with your MediaWiki username and pagename with the name of the page you want to create in the URL: https://www.mediawiki.org/wiki/User:username/Sandbox/pagename

Duplicate template content[edit]

The MediaWiki Action API template is used to maintain consistency among the pages and to provide useful links to users. Fill your Sandbox page with the content from this template.

To do so:

Go to: API:Documentation template.
Click on 'Edit' -> 'Edit source' in the top bar.
Copy the content of the source.
Go to your Sandbox page and click on 'Edit' -> 'Edit source' or 'Create page'.
Paste the copied contents in your Sandbox page.
Scroll down and select 'Show preview' to preview your page before saving.
Write a 'Summary' and click on 'Publish page' to save the page.

Improve the API page[edit]

You can now start improving the API page in your Sandbox. Go through the content on the original page, check the accuracy of the content and add it to the template in your Sandbox.

Refer to the pages on Help:Editing to learn about editing wiki-pages.
We encourage you to stick to the template. If you feel the need to add/remove any section from the template or make any other changes, make sure to discuss it with your mentors first.
To fill the 'Parameter history' section, check the history of the original page. (Click on 'View history' in the top bar and compare different versions.)
Make sure that your page is easy to translate. See Page translation example.

Examples[edit]

For your reference, here are API pages modified using the new template:

Contribute sample code[edit]

Contribute sample codes for the API page (that you selected) to this repository: MediaWiki Action API Code Samples. Make sure to read the contribution guidelines before beginning.

When you're done[edit]

Reach out to your mentors (@jeropbrenda) on Zulip to get feedback on your contributions.
Try to incorporate the feedback received.
After getting a green signal, coordinate with your mentors in getting your changes integrated with the actual page on MediaWiki.org.
Lastly, add your name next to the project in the 'Done' column in the Phabricator task description.
Now, you can choose another API page to work on, or look into contributing to other open tasks. If your patches get merged, you can record them in your application. Here are some useful links:

Additonal notes[edit]

MediaWiki pages[edit]

Use the 'table of contents' to jump to different sections within the same page.
Use the 'Seach MediaWiki' bar on the top-right for searching MediaWiki pages.

Using Zulip[edit]

See: Zulip user guide

Outreachy-19 discussions take place on: https://wikimedia.zulipchat.com/#narrow/stream/outreachy19.
Learn about Zulip streams and topics: https://zulipchat.com/help/about-streams-and-topics.
Learn how to format messages on Zulip: https://zulipchat.com/help/format-your-message-using-markdown.
Make sure to always use respectful, friendly and inclusive language on the chat platform.

Using Phabricator[edit]

See: Phabricator/Help

Subscribe to the task:T232816 to get notified when changes are made to the task.
Learn about the markup language used on Phabricator: Remarkup Reference.

Help[edit]

If you have any questions or need help, you can reach out to the Wikimedia community over:

Guidelines:

Always use respectful, friendly and inclusive language in discussions with the Wikimedia community.
Try to frame specific and clear questions to ask the community.
Follow the Code of conduct strictly.