Developer Portal

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.

Timeline
Note that this timeline is not final.
 * Jul 2020‒Sep 2020: Announce project; set up wiki page ✅
 * Oct 2020‒Feb 2021: First iteration: Explorative conversations with a sample of stakeholders (WMF/WMDE) to identify use cases and identify key technical documents to link, understand workflows, and gather technology areas (T260984) ✅
 * Jan 2021‒Mar 2021: Review of single entry points of other projects and organizations (T260987) ✅
 * Mar 2021‒Apr 2021: Analysis of exploratory conversations, leading to key themes and to a content proposal for a single entry point ✅
 * May 2021: Publication of key themes identified in exploratory conversations: ✅
 * May 2021: Publication of a content proposal (prototype) for an initial single entry point: Developer Advocacy/Developer Portal/Content Draft ✅
 * May 2021: Call for review and feedback by the broader community (T260985) of the prototype at Developer_Advocacy/Developer Portal/Content Draft/Feedback ✅
 * May 2021‒Jun 2021: Discussion, identification, and incorporation of potential improvements to the prototype: ✅
 * Jul‒Sep 2021: Investigate further content strategy for a single entrance point ✅
 * Jul-Aug/Sep 2021: Define accuracy criteria for checks of content linked from the prototype - see tag/key_docs_update_2021-22 (planning) and Documentation/Review process (outcomes) ✅
 * Oct 2021‒June 2022: Correctness checks (based on Documentation/Review process) of content linked from the prototype and conversations on potential improvement of processes around key technical documents (structure, locations, navigation, stewardship, etc), by potentially also utilizing the Documentation/Maturity model for MediaWiki technical documentation to improve practices and processes - see tag/key_docs_update_2021-22
 * Jul‒Sep 2021: Investigate technical requirements for implementation of a single entrance point ✅
 * Oct 2021‒May 2022: Technical implementation of a single entrance point
 * Work in progress prototype ✅
 * Apr-May 2022: User testing of final prototype (See ) ✅
 * June 2022: Launch of the developer portal

Key themes from conversations
This is a summary from the explorative conversations with a sample of stakeholders (WMF/WMDE) in Oct 2020‒Feb 2021.


 * Wikimedia has a large variety of programming languages and technology areas. Documentation in many of these could benefit from more visibility.
 * Audiences: A clear understanding of the audiences for technology areas helps write more focused docs and consumers get more relevant information.
 * Stewardship: Tech writers serve as the main contact for technical documentation. In the absence of technical writers, stewardship of documentation is ad-hoc.
 * Stewardship: Defining stewards for specific technical areas and processes for task assignees or code reviewers to review related documentation improves correctness and completeness of documentation.
 * Coherence: Guidelines and recommendations on naming and structuring documentation would help documentation writers and maintainers.
 * Coherence: Guidelines on which content should be hosted on which sites would help reach the target audiences and avoid duplication of content.
 * Common knowledge: Clarifying (and potentially expanding) the set of shared public documentation to be considered relevant for a wide range of technical contributors could help improve accuracy and completeness of documentation.
 * Code proximity: The closer technical documentation is to the code that it covers, the more likely the related documentation can be located and updated.

Feedback from broader community and outcomes
After the exploratory conversations (see ) which informed the initial content proposal, the public feedback phase to receive broader feedback on the content draft took place from May 6 to May 25, 2021.

The call for feedback was published in various places: Several mailing lists (wikitech-l (reminder), pywikibot, cloud, wikidata, wikitech-ambassadors, analytics), IRC channels, social media channels, Zulip, the Hackathon Telegram group, etc. There was also a dedicated Hackathon 2021 session in which people commented on this project.


 * We received feedback from several longtime contributors on the Feedback page, via private messages, and several people attending the Hackathon 2021 session.
 * Several comments expressed appreciation for the idea and initiative.
 * Several comments proposed technologies to add, descriptions and categories to improve, potential links to add, and items to move to other categories. This feedback was mostly included.
 * It was pointed out that some headers partially duplicate descriptions. We made some improvements and think this cannot be completely avoided.
 * It was pointed out that some relevant information is on Developer Hub and that people wouldn't immediately think of looking into that page. We may want to evaluate scope, visibility, and stewardship of the Developer Hub page. The page seems to be a valuable link hub for MediaWiki development itself.
 * It was proposed to evaluate search logs to better understand common needs. This has been filed as T285183 to be considered at a later stage.
 * We added TemplateStyles and Wikidata Query Service. We removed VisualEditor.
 * We moved Wikibase to the "Enhance the MediaWiki software platform" section.
 * We moved Machine Learning to the "Build tools, gadgets and bots for your Wikimedia community" section.
 * We improved descriptions and titles to be clearer and more consistent.

User research and testing
After the public feedback phase, the team completed multiple rounds of user research and UX testing as we iterated towards the launch version of the dev portal.

User research during development
From 2021 Sept - Nov, we conducted 4 user tests to assess prototypes of the dev portal and to guide its ongoing design and implementation. The goal of this round of testing was to assess user reactions to the dev portal design and determine if they could complete basic information-seeking tasks using it. We were especially interested in how users would feel about navigating a multi-layer site structure vs. a more flat stucture.

Key takeaways:


 * A single point of entry is essential for newcomers, ideally to provide sequential onboarding and a gentle "on-ramp". Beyond that, topic- or audience-focused portals are a better way to handle the large amount of information without overloading people.
 * Trustworthiness and signals around the freshness and accuracy of the info is extra-important due to the wiki context.
 * Terminology is confusing (so many wikis, so many different types of technical contributions).
 * A wall of text is off-putting; people like the prototype that has more space and icons, but they prefer the action-oriented and more clear textual content of the second prototype.
 * Audience: people want links that are relevant to their user type; there's a difference between what community developers would look for in a portal vs. "general" or MediaWiki developers.
 * Users were able to navigate and felt good about the multi-layer site structure.

Some specific tasks and content we tested were:


 * Contribute to Wikimedia open source: performed positively; people understood what this meant and when to click it.
 * Build tools: performance mixed; people aren't sure if extensions are tools, sometimes they may confidently click on this when looking for MediaWiki developer info, or for data dumps (they are confidently wrong about what they'll find here).
 * Research data and machine learning: people didn't click on this even when their task clearly involved "getting and using data". This resulted in us changing the way this content is represented in the portal.
 * Wikipedia APIs: people usually ended up here in a roundabout way when their task ultimately could be solved by using an API (i.e. "reading API" to solve the task of accessing content for a tool they're building).

User research on final prototype
For this final round of user testing, we worked with UX researchers from the WMF Design Strategy team to coordinate testing and recruit participants from a larger and more diverse set of contexts, including people who aren't familiar with Wikimedia or its open source technology projects.

Participant overview
We did a total of 9 tests with participants from 4 user groups:

Findings and outcomes
Overall, the site was effective in helping users find the information they were looking for. Participants responded positively to the design, navigation, and organization of the site. Some specific findings in thematic areas:

Navigation:
 * While different people gravitate towards different navigation menus, the engagement with left nav, horizontal nav, and in-page nav indicated that they're all useful.
 * Nearly everyone opened the site wide enough to view the horizontal nav and sidebar.
 * Participants mostly used the Search box only when prompted, though a few used it without prompting. Overall, it worked effectively.

General usability:
 * Translation icon was easily understood. Users had positive responses to availability of multilingual content, though even multilingual testers said they'd probably still use the site in English.
 * The site is quick, responsive, and easy to use.
 * Tooltips and link text helped users understand what links did / where they went.
 * People were okay with jumping from the portal to a wiki.
 * The Get Started button was useful and almost all users clicked it.

Content:
 * Users gravitated towards tutorials, and found them quickly.
 * Users expected more content on the Get Started main page, and especially wanted to browse content by programming language.
 * Open source contributors wished for a comprehensive and sortable/filterable list of projects with basic metadata to help them decide which projects to explore further.
 * Users were surprised by the absence of MediaWiki in the list of open source projects.
 * Tech Blog was a popular link in the Updates section.
 * Some users expected a login feature as is common on most wikis.

Design:
 * The dark mode toggle icon was incomprehensible to almost all participants.
 * Some of the site spacing and padding was visually unpleasing or inconsistent in a way that bothered people.
 * The site title behavior is inconsistent with common practices.
 * Overall layout and presentation was viewed positively as being clean, simple, and avoiding the info overload common on wiki sites.
 * Most testers did not recognize the Wikimedia logo.

Our research findings resulted in the following changes for the Developer Portal:

Content revisions:
 * Reworded tutorial headers to improve clarity; made all headings task-oriented
 * Changed section index pages to use H2 links instead of "Learn more" links
 * Moved developer app guidelines and licensing info out from under “discover available wikis” to make the content easier to find
 * Moved Java-specific open source projects higher on the page due to popularity of the language among testers.
 * Moved up the Tech Blog on the updates page because it performed well in testing

Content additions:
 * Added more text to describe link content and improve search recall of documents
 * Added programming language browse options to Get Started section
 * Added Get Help link to home page (instead of just nav bar)
 * Added link to MediaWiki YouTube channel as a way to learn about Wikimedia tech in Get Started section; removed tech talks link
 * Added the names of outreach programs to the description for that link
 * Added MediaWiki as a topic for open source contributions. Even though it's not newcomer-friendly, its absence was surprising and notable.
 * Added the Wikidata infrastructure overview doc to section on Technical Operations

Design adjustments:
 * Improved color contrast
 * Changed alignment of site icon and site title
 * Removed paragraph symbols from homepage
 * Changed dark mode toggle icon

Previous plans, thoughts and research
This list includes historical attempts to establish either some high-level developer documentation hub or holistic approaches to improve cross-project documentation. This list is not about specific content itself.


 * WMF Projects/Technical Documentation and User:Zakgreant/MediaWiki Technical Documentation Plan (2010) "by making small, incremental improvements to the existing documentation process and infrastructure."
 * Requests for comment/Documentation overhaul on MediaWiki Core level (2011)
 * Requests for comment/Add developer link to footer of Wikimedia wikis (2012)
 * T67074 (2014-2015) - "Set up dev.wikimedia.org portal"
 * Web APIs hub (2013-2015); see T308/T299 and notes about a Data & Developer Hub from a Hackathon
 * User:Quiddity (WMF)/Hubs and docs (2017), notes on older existing pages
 * User:Waldyrious/Docs (2013-2019)
 * T169599 (2019) - "Sort out concept for overview/entrance pages targeting our developer audience" (about pages on mediawiki.org only)
 * Core Platform Team/Initiatives/Developer Portal (2019-2020), superseded by lowering scope to an API Portal / API Gateway

Existing high-level entry points
This list is not about specific technology areas but common landing points, either by domain or by links often pointed out to interested newcomer developers.


 * https://www.mediawiki.org (MediaWiki core/extensions/skins, but also random Wikimedia related technology)
 * https://www.mediawiki.org/wiki/New_Developers (new Wikimedia developers) and sometimes https://www.mediawiki.org/wiki/Good_first_bugs
 * https://www.mediawiki.org/wiki/How_to_become_a_MediaWiki_hacker (new MediaWiki core/extensions/skins developers)
 * https://www.mediawiki.org/wiki/Developer_hub (experienced MediaWiki developers)
 * Existing sites:
 * https://mediawiki.org (MediaWiki core/extensions/skins/platform, random other technical things and home of some team pages; in theory not intended for Wikimedia-specific technical documentation)
 * https://wikitech.wikimedia.org (Wikimedia infrastructure/servers/network, Toolforge and Cloud VPS, Analytics - Docs related to technical projects and infrastructure maintained by WMF; how we use software and how it's configured)
 * https://doc.wikimedia.org (API references for classes) (technical details on content generation; frontpage structure)
 * https://meta.wikimedia.org (less technical; mostly cross-Wikimedia movement stuff for coordination, planning, documentation; some random Wikimedia related technology, maybe home of some engineering team pages)
 * https://api.wikimedia.org/
 * Several external project-specific websites, e.g. https://wikiba.se, https://kiwix.org/, https://commons-app.github.io/, etc. Some of them are self-hosted static microsites, e.g. research.wikimedia.org
 * https://wikimediafoundation.org/technology/
 * https://meta.wikimedia.org/wiki/Tech (as a portal split, recommended by Small wiki toolkits)

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


 * Content re-users
 * I want to use Wikimedia content in my app.
 * I want to download Wikimedia content to use in an offline app or to host a mirror.
 * I want to find reference information for something specific.
 * User journeys:
 * 
 * 


 * Developers (experienced)
 * I want to build my open source programming portfolio to gain experience for employment.
 * I want to use my technical skills to give back.
 * I want to find co-maintainers for my tool.
 * I want to improve my tool's docs and discoverability.
 * I want to experiment with new technology.
 * I want to work on a large scope project in collaboration with WMF, affiliates, and communities.
 * I want to move my tool onto Wikimedia Cloud.
 * I want to connect with other experienced devs.
 * I want to create or improve a tool.
 * I want to find out what other people and teams are working on.
 * I want a general overview of the tech stack and systems.
 * I want to share what I'm working on or something cool that I built.
 * I want to know who is responsible for something/who I can talk to about a specific topic or technology.
 * User journeys:
 * 
 * 
 * 


 * Developers (new)
 * I want to solve a problem on my local wiki.
 * I want to grow my technical skills.
 * I want to build my open source programming portfolio to gain experience for employment.
 * I want to share what I'm working on or something cool that I built.
 * I want to find reference information for something specific.
 * I want a general overview of the tech stack and systems.
 * I want to find out what other people and teams are working on.
 * I want to know who is responsible for something/who I can talk to about a specific topic or technology.
 * User journeys:
 * 
 * 
 * 


 * Outreach program participants
 * I want to learn about and apply for outreach programs.
 * I want to complete the evaluation phase for an outreach program.
 * I want to be successful in my outreach program.
 * I want to mentor outreach participants.
 * I want to find reference information for something specific.
 * I want a general overview of the tech stack and systems.
 * I want to connect with the larger technical community.
 * I want to know who is responsible for something/who I can talk to about a specific topic or technology.
 * User journeys:
 * 


 * Data consumers (Researchers)
 * I want to use data from Wikimedia as part of my research.
 * I want to use data to understand my wiki, Wikimedia projects, and Wikimedia users.
 * I want to use an example dataset for data science purposes.
 * I want to find reference information for something specific.
 * I want a general overview of the tech stack and systems.
 * I want to find out what other people and teams are working on.
 * I want to connect with the larger technical community.
 * I want to know who is responsible for something/who I can talk to about a specific topic or technology.
 * User journeys:
 * 
 * 

User journeys
The following user journeys 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.

Get started
✅ 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
✅ Phabricator task | portal link


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

Build and discover tools
✅ Phabricator task | portal link


 * Discover and share tools
 * Get started building tools
 * Learn with tutorials
 * Explore frameworks and APIs
 * Host tools on Wikimedia servers

Contribute to Wikimedia open source
✅ Phabricator task | portal link


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

Connect and learn
✅ 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

Key landing pages
The team has identified these pages as key documentation landing pages representing sets of key docs.

On mediawiki.org
To help maintain these pages, add this list to your Special:EditWatchlist/raw watchlist, and make sure your preferences are set to Email me when a page or a file on my watchlist is changed to receive edit notifications.


 * Accessibility guide for developers
 * API:Main page
 * Architecture Repository
 * Code of conduct
 * Communication
 * Developers/Maintainers
 * Development guidelines
 * Documentation
 * Good first bugs
 * Hackathons
 * How to contribute
 * Localisation
 * Manual:Creating a bot
 * Outreach programs
 * Security
 * Technical Community Newsletter
 * Technical Decision Forum
 * Wikibase
 * Tech talks
 * Wikimedia Technology
 * MediaWiki
 * MediaWiki

On wikitech.org
To help maintain these pages, add this list to your Special:EditWatchlist/raw watchlist on Wikitech, and make sure your preferences on Wikitech are set to Email me when a page or a file on my watchlist is changed to receive edit notifications.


 * Deployments
 * Help:Cloud Services Introduction
 * Help:Toolforge/Developing successful tools
 * Portal:Toolforge
 * Wikimedia infrastructure

On meta.wikimedia.org
To help maintain these pages, add this list to your Special:EditWatchlist/raw watchlist on Meta-Wiki, and make sure your preferences on Meta-Wiki are set to Email me when a page or a file on my watchlist is changed to receive edit notifications.


 * Grants
 * Offline Projects
 * Research:Data
 * Small wiki toolkits
 * Tech News
 * Wikimedia Apps

Off wiki

 * toolhub.wikimedia.org
 * doc.wikimedia.org
 * performance.wikimedia.org
 * techblog.wikimedia.org
 * design.wikimedia.org/style-guide

Technical implementation
See Developer Portal

How to contribute
See Developer_Portal