Screenshot of developer.wikimedia.org

New discovery tool for technical documentation

The Wikimedia Developer Portal guides technical audiences to key documentation and community resources. By organizing links into thematic sections focused on developer tasks, it helps people more easily find information about Wikimedia technology.

The technical community now has a new tool to discover information. The Developer Portal is a centralized entry point to help you:

  • Find the key documentation you need for common developer tasks.
  • Discover available tools and technologies.
  • Learn how to get started in Wikimedia technical areas.

For a general overview of this project, see the companion post on Diff; the following post focuses on details of the Developer Portal relevant to technical audiences.

Design principles

At its core, the Developer Portal is an index of categorized links to key sources of technical information. These sources are hosted primarily on wikis—the portal contains no actual documentation. 

Technical writers, developer advocates, software engineers, and designers worked together to create the Developer Portal, with lots of input and feedback from the community. We did user research, analyzed documents, created a content strategy, and implemented the portal as a static site. 

In designing the Developer Portal, we followed these principles:

  • Progressive disclosure: Avoid information overload by limiting the amount of content on each page. Provide only relevant, contextualized information at each step.
  • Well-lit paths: Focus on the most important and reliable resources. Do not attempt to index documentation for all Wikimedia technologies. Prioritize content that lowers barriers to entry.
  • Inclusivity: Support the widest set of developers (See the Diff blog post for details.) This includes providing translations, and making the portal accessible and usable on low-speed internet connections.

Paths to explore

Browse tutorials

Tutorials are crucial to help developers get started with Wikimedia technology, but it can be hard to find tutorials when they live on different wikis.  The Developer Portal makes it easier to browse available tutorials:

Explore by programming language

In feedback sessions and user testing, developers often express a desire to browse documentation and projects by programming language. The Developer Portal provides several paths to do that:

Find community and educational resources

It can be hard to keep up with all the events, news, and opportunities in the technical community! The Developer Portal brings together some essential resources to help people stay connected:

Technical architecture

The navigation-focused design of the portal made its implementation different from a standard, content-focused website. We wanted to use a static site generator to simplify the process of constructing and rendering the portal, but we didn’t want to create many pages with paragraphs of written content. Instead, a single page on the portal displays a collection of links to wiki pages or other key technical resources. We wanted to maintain only a single description of each key technical resource, and be able to easily combine or transclude those units to create modular collections of links.

The Developer Portal site is generated by MkDocs using the Material for MkDocs theme. We built custom plugins to integrate with translatewiki.net and to render markdown pages based on categorized sets of links, which are described in YAML files.  For more implementation details, see the Developer Portal docs on mediawiki.org.

Ongoing and future work

So far, the portal is 100% translated into French, Macedonian, and Turkish. If you can help add translations in more languages, visit the project’s page on translatewiki.net!

In the future, we plan to do more user testing in languages other than English, and we’d also like to test with users of assistive technology.

A major part of this project includes reviewing and updating the key documents linked from the Developer Portal.  We’re continuing that work into the coming year, and also investigating how to improve and scale the process.  Helping the technical community find documentation is just the first step—the larger goal is to empower everyone to contribute to and benefit from high-quality, reliable information about Wikimedia technical projects.

Learn more

Leave a Reply

Your email address will not be published.