Documentation/Contribute
This page provides an overview of ways to get involved in Wikimedia technical documentation work.
How to contribute to Wikimedia tech docs
[edit]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
[edit]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.
- Be familiar with the basics of wiki editing.
Finding doc tasks
[edit]- 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 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
[edit]- Follow the technical documentation style guide.
- If you're staring a new doc, use a template to help you create and structure your content.
Working with translated content
[edit]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
[edit]- 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
[edit]- 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
[edit]See Documentation/Contribute/Filing documentation tasks.
Historical outreach and community programs
[edit]2024 January: At the Wiki Mentor Africa Hackathon 2024, Alex Paskulin presented a workshop, "Technical Documentation 101".
2023 May: At Wikimedia Hackathon in Athens, Kosta Harlan led a session about how to improve your technical writing.
2022 May: At the Wikimedia Hackathon, Tricia Burmeister gave a talk 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
[edit]- 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
[edit]- 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.