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:

Finding doc tasks

  • In Phabricator, you can find potential good first documentation bugs by searching for tasks tagged with "documentation" or "tool-documentation" and "good first task". However, these tags are not always 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 and Phabricator tasks for any recent updates related to documentation. If you're planning to make large changes, investigate whether there are key stakeholders or active project maintainers you should discuss your ideas with before you implement them.

While working on docs

Working with translated 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 {{DoNotTranslate}}, {{Draft}} or {{Work in progress]} to discourage translation or other major edits while you're changing the doc.
  • Don't ever manually add the little <!--T:4--> "translation unit markers". The software needs to add those. They are implicitly connected to the chunks of text that are sent into the translation interface. They appear before paragraphs, or after headings.
  • If you move a block of text, move the "unit marker" along with it.
  • Include empty-lines between each header and paragraph block. That's how the software keeps the blocks separated.
  • If you delete translation unit markers, but retain the text, then translators must either re-translate that text (into every language), or spend time re-associating the correct unit markers that had been used.
  • Try to minimize big changes after you mark a page for translation. Avoid frequent changes to the wording of a single paragraph many times over the course of a few weeks. If a volunteer is trying to keep a page up-to-date, they'll have to rewrite it every time.

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.
  • Remove any templates you may have added while editing, like {{DoNotTranslate}}, {{Draft}} or {{Work in progress]}.

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.

How to file documentation tasks or requests

See Documentation/Contribute/Filing documentation tasks.

Outreach and community programs

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

  • 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.