Developer Portal
The Developer Portal is a static website that helps people find Wikimedia technical documentation.
|
Wikimedia Developer Portal
A central place for developers to find Wikimedia key technical documents
|
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]- 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
[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]
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] 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] 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] 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] 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]- ↑ https://colinmorris.github.io/blog/unpopular-wiki-articles
- ↑ 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).