Developer Portal

Group:	Wikimedia Technical Engagement
Start:	2020-08
End:	2022-06
Backlog:	phab:tag/Wikimedia-Developer-Portal
Lead:	Andre Klapper

The Developer Portal is a static website that helps people find Wikimedia technical documentation.

Go to the Developer Portal Browse the repository

Problem

"Upon arriving on the MediaWiki and Wikitech home pages, I was instantly lost." -- Ashwin Bhumbla

"MediaWiki documentation is not only infamously incomplete, but also terribly scattered." -- Waldyrious

Wikimedia has many potential entrance places for developers interested in certain technical areas. Based on conversations on Project:Support desk, mailing lists, IRC, Phabricator, in outreach programs, etc., some technical contributors have a hard time finding the information and key technical documents that they are interested in.

Some documentation should be more discoverable, some documentation is dispersed or duplicated across several websites, some of our documentation is outdated, some of our technology areas could be more discoverable.

Goal

Starting in 2020, the Developer Advocacy team works on an organization strategy for key technical documents: Understand challenges about finding and maintaining docs, identify key docs, and investigate ways to improve our workflows around documentation.

One tangible outcome of this initiative will be a central and single entry point ("developer portal") which links to our key technical documents.

This will allow existing and future technical contributors and developers to:

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

Further outcomes include checking the documents linked from the single entry point proposal for accuracy, and investigating improvements of processes around technical documentation.

Scope

Wikimedia: The Developer Portal is restricted to code related to Wikimedia free knowledge projects, such as Wikipedia and Wikidata. It does not duplicate the navigation of mediawiki.org or serve people interacting with non-Wikimedia instances of MediaWiki.
Developer: The Developer Portal covers how to write and interact with Wikimedia code. In order to define a clear, manageable scope, we've decided to exclude content about creating MediaWiki templates from the Developer Portal. The scope of the Developer Portal includes MediaWiki parser functions, Scribunto Lua scripting, user scripts, APIs, data sources, and other Wikimedia technical projects. The goal of this scope is to be inclusive of everyone interacting with Wikimedia code, regardless of whether they consider themselves developers.
Portal: The Developer Portal contains no documentation content. It is a navigation tool that links to docs hosted elsewhere, primarily on wikis.

Principles

Progressive disclosure: To avoid information overload, limit the amount of content on each page. The Developer Portal aims to funnel users into specific contexts based on their goals, providing only relevant, contextualized information at each step.
Well-lit paths: The Developer Portal is not meant to be an exhaustive index of all Wikimedia technologies and documentation. To provide the best user experience possible, the Developer Portal should link to the best available documents and technologies that help accomplish a given task. The Developer Portal should not link to technologies that are experimental or redundant with other, more established technologies. Whenever possible, the Developer Portal should prioritize workflows that lower barriers to entry.
Inclusivity: The Developer Portal is designed to support the widest possible set of developers, including support for multiple languages, accessibility tools, and low-speed internet connections.

License

Wikimedia Developer Portal code and configuration is licensed under the GPL-3.0-or-later license. Textual content is licensed under the CC-BY-SA-4.0 license.

Image credits

Wikimedia logo by Neolux, public domain, via Wikimedia Commons
Wikimedia favicon by the Wikimedia Foundation, CC BY-SA 3.0, via Wikimedia Commons
Adapted Wikipedia 20 illustrations by Jasmina El Bouamraoui and Karabo Poppy Moletsane, CC0 1.0, via Wikimedia Commons. Black backgrounds were removed from images used in dark mode.

Core audiences

These personas and motivations have been identified for the proposed Wikimedia portal.

Experienced tool developers: Active Wikimedians who have created or contributed to Wikimedia tools; User journeys: #Build and discover tools, #Connect and learn
New tool developers: Active 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. They may not consider themselves developers.; User journeys: #Build and discover tools, #Connect and learn
Open source contributors: Developers who want to use their skills to contribute to Wikimedia. They may be volunteers or employees of the Wikimedia Foundation or affiliates.; User journeys: #Contribute to Wikimedia open source, #Connect and learn
Content reusers: Developers who want to use Wikimedia content in their projects, usually with read-only access. They may or may not be active Wikimedians.; User journeys: #Use content or data, #Get started
Data consumers and researchers: Data scientists, machine learning engineers, and researchers who want to use Wikimedia data in their projects.^[1] They may or may not be active Wikimedians.; User journeys: #Use content or data, #Get started
Students: Students who are learning programming and are interested in Wikimedia. They can be university students, independent learners, or outreach program participants.; User journeys: #Contribute to Wikimedia open source, #Connect and learn

User journeys

The following user journeys ^[2]evolved out of our research into user personas, motivations, and the tasks that users are trying to complete when they seek documentation. The information architecture of the developer portal implements these goals and tasks as site sections and links to key landing pages. Read more about this in our corresponding blog post on Diff.