Illuminating pathways to technical documentation

Wikimedia has many entrance points for developers and technical contributors. Our technical community includes people with a wide range of skills, experience, and interests—from students learning to build their first app, to professional software engineers with deep knowledge of MediaWiki. Many developers use APIs to access free knowledge content, and many volunteers contribute their technical skills to Wikimedia open source projects.

Today, the Wikimedia Foundation Developer Advocacy team is launching a new, centralized entry point for finding technical documentation and community resources: the Wikimedia Developer Portal. Just like the community itself, our technical documentation takes many forms and resides in many different places. From mediawiki.org to GitHub to Wikitech, the key information developers need may exist in wiki pages, code repositories, websites, and more. This complex landscape can make it hard to find the information you need. The goal of the the Developer Portal project was to make it easier for developers and technical contributors to:

  • Find the information they need to achieve a certain task.
  • Discover available tools and technologies.
  • Learn how to get started in Wikimedia technical areas.

Understanding audiences and their documentation needs

Part of the complexity of Wikimedia technical documentation comes from the multiple audiences it serves. The new Developer Portal seeks to support the following types of users:

A person sitting on the floor working on a laptop with a W on it

Content reusers

Developers who want to use Wikimedia content in their projects.

A person drinking a hot drink while sitting at a laptop

Data consumers and researchers

Data scientists, machine learning engineers, and researchers who want to use Wikimedia data in their projects.

Two people sitting cross-legged while working on their computers. They seem to be discussing code.

Tool developers

Wikimedians who have created or contributed to Wikimedia tools.

A person sitting in front of a computer with bugs on it. The person is scratching their head.

New tool developers

Wikimedians who are interested in learning to create, contribute to, and use Wikimedia tools, usually to solve a problem they face in maintaining their local wiki.

A person in a wheelchair celebrating while holding a laptop in celebration of the Wikimedia 2022 Hackathon

Open source contributors

Developers who want to use their skills to contribute to Wikimedia technical projects.

Two people with laptops and speech bubbles above their heads. One person has a cane.

Learners

Students who are learning programming and are interested in Wikimedia technical projects.

Each of these audiences has different (but often overlapping) goals, motivations, and tasks to complete. They have different information needs and may rely on different types of documentation. How can we help all these types of users find what they need without risking information overload?

To begin, we talked with stakeholders, gathered community feedback, and reviewed previous research about developer documentation hubs. We then completed multiple rounds of user research to identify the major user journeys for each audience. A user journey captures the steps to complete a specific task. For example, the user journey below illustrates the steps a new developer might take to start contributing code to a Wikimedia open source project:

Example user journey for open source contributors

Applying user journeys to guide our content strategy enabled us to identify the key docs necessary for each step in the journey. Key docs might be landing pages for a major technical area, tutorials for a given topic, or overviews that explain essential concepts. 

Improving technical docs and processes

This project involved an entirely new user research process for our team. We worked with the Wikimedia Foundation Design Strategy team to design a research study and recruit a diverse group of users to test the final version of the site. We learned a lot from this process! Here are some key takeaways:

  • User types overlap more than we expected.
  • People have very different navigation behaviors: some use menus heavily, others use page content, and sometimes that behavior changes based on context. Offering multiple paths to information is important.
  • Users appreciate the option to view content in languages other than English, but most developers say they would still use the site in English because that’s the language of most technical content. 

Helping users discover key technical docs is only part of the solution; the information in those docs must also be reliable, updated, and user-friendly.  To ensure that the Developer Portal links to high-quality documentation, we developed a documentation review process.  It currently includes checklists to standardize documentation reviews and make it simpler for anyone to help improve documentation. We’ve used this process to review and improve over 20 key docs so far, and we’re continuing to streamline and scale the process. While work in this area continues, today’s launch of the Developer Portal is an exciting step towards better empowering developers to share in the sum of all knowledge.

Learn more

Image credits: Mam’Gobozi Design Factory (MDF), CC BY-SA 3.0, via Wikimedia Commons