Documentation/Contribute

This page provides an overview of ways to get involved in Wikimedia technical documentation work.

How to contribute to Wikimedia tech docs
Contributions from everyone are essential to keeping tech docs healthy -- thank you for wanting to help! The following sections outline some guidelines and best practices for working on documentation within the Wikimedia technical community.

Before you start
The same guidelines and etiquette that apply to code contributions and wiki editing also apply to technical documentation:


 * For documentation on wikis, collaborators interact on the Talk pages, but may also use Phabricator tasks, Gerrit (code review), mailing lists and additional group chats like IRC.
 * Before you update or create documentation:
 * Read and understand the guidelines for How to start contributing.
 * Read and follow the Communication tips and Wikimedia's Code of conduct.

Finding doc tasks

 * In Phabricator, you can find potential good first documentation bugs by searching for tasks tagged with "documentation" and "good first task". However, these tags are not well-curated, so you may find tasks that are not actually simple or good first tasks. Read the full task history and ask questions if you can't figure out how (or whether) to proceed.
 * Documentation work isn't always tracked in Phabricator. Please improve documentation regardless of whether it has outstanding Phabricator tasks! Before you do that, make an effort to understand the previous work done on a project and its documentation. Review Talk pages, Phabricator tasks, and past documentation patches. Are there key stakeholders or active project maintainers you should discuss your ideas with before you implement them?

While working on docs

 * Follow the technical documentation style guide.
 * If you're staring a new doc, use a template to help you create and structure your content.
 * If the doc you're editing is translated:
 * Fixing a typo is simple - Simply fix it! No other steps needed. It's likely that a translator noticed the typo, but ultimately knew what you wanted to say, and translated it accordingly.
 * If you're making more substantial changes than a few typos, add a template like,  or {{Work in progress]} to discourage translation or other major edits while you're changing the doc.
 * When making substantial edits or additions: do not add text within translation tags. If you need to, move the translation tag to just before the part you will be editing, and add a new set of translation tags.

Example:

This text is already translated and is unit T1

This text is in a new set of translate tags because it's changed and must be translated as a new unit

Before you publish

 * Review what you wrote to make sure you use inclusive language.
 * Use a checklist to review your doc for common issues and key quality criteria.

After you publish

 * Verify that your changes follow accessibility guidelines. Use the WAVE tool to check for major issues.
 * View your content on a mobile device and check that it renders correctly and that all information is visible.
 * Monitor the relevant Talk page, Phabricator task, or other communication forums. Reply to comments or feedback on your changes.

Historical outreach and community programs
2022 May: At the Wikimedia Hackathon, we had a discussion and gathered community input around documentation challenges, needs, opportunities, and priorities.

2022 July-Sept: Developer Advocacy tech writer quarterly goals are focused making it easier to assess the state of documentation and contribute meaningful improvements (project board in Phabricator). This includes work to:
 * Identify documentation collections and how to assess the state of the content they contain.
 * Make the results of this assessment publicly available and easy to navigate.

Friends of the docs

 * Wikimedia technical documentation: Friends of the Docs - Are you interested in connecting with other folks who are interested in Wikimedia, open source software, and technical documentation? Friends of the Docs meets from time to time to discuss documentation-related issues. There is also a Friends of the Docs Zulip stream where you can ask questions and start discussions.

Outreach programs

 * Google Season of the Docs - This program pairs technical writers with open-source organizations to improve technical documentation.
 * Outreachy - Outreachy is a diversity initiative that provides paid, remote internships to people subject to systemic bias and impacted by underrepresentation in the technical industry where they are living. Outreachy rounds often include projects based around technical documentation.