New discovery tool for technical documentation
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:
- Get started building tools and bots that interact with Wikimedia projects
- Learn to use Wikimedia APIs to access wiki content or data
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:
- Developers looking to contribute to Wikimedia open source projects can browse projects by programming language. The featured projects are a subset of projects that are written in popular programming languages, actively maintained, and have clear contributing guidelines.
- Developers who want to browse client libraries by programming language or explore the codebase by language can use the portal to quickly navigate to key wiki pages and repositories.
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:
- Events listings for different technical audiences
- Learning and mentorship opportunities
- Updates and news about technical topics
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
- For a more general overview of this project, see the companion post on Diff.
- To propose or contribute code, content, or translations for the Developer Portal, see the docs on mediawiki.org.
- The source code is available on Gerrit.