Developer Portal

From mediawiki.org

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

Go to the Developer Portal Browse the repository


Problem[edit]

"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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

Core audiences[edit]

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[edit]

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.

Get started[edit]

Yes Done Phabricator task | portal link

Tasks:

  • Learn how Wikimedia software projects work
  • Browse tutorials
  • Learn about Wikimedia technology
  • Browse by programming language

Use content or data[edit]

Yes Done Phabricator task | portal link

  • Use content and data
  • Explore featured apps
  • Learn with tutorials
  • Use wiki content
  • Access open data

Build and discover tools[edit]

Yes Done Phabricator task | portal link

  • Discover and share tools
  • Get started building tools
  • Learn with tutorials
  • Use APIs and data sources
  • Host tools on Wikimedia servers

Contribute to Wikimedia open source[edit]

Yes Done Phabricator task | portal link

  • Learn how contributing works
  • Contribute by topic
  • Contribute by programming language
  • Search Wikimedia open source projects

Connect and learn[edit]

Yes Done Phabricator task; Phabricator task | portal link

  • Connect at hackathons and events
  • Communicate with the tech community
  • Learn and share technical skills
  • Get tech project updates
  • Learn about Wikimedia technical operations

Feedback[edit]

To share your feedback, leave a comment on the discussion page.

Maintainers[edit]

The Developer Portal is maintained by the Wikimedia Technical Documentation Team.

References[edit]

  1. https://colinmorris.github.io/blog/unpopular-wiki-articles
  2. Technical writers use user journeys as a framework for information design that follows the principles of minimalism (or task-orientation), and layering (or progressive disclosure).