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

Based on impressions on Project:Support desk, mailing lists, IRC, Phabricator, in outreach programs, etc., we have many potential entrance places for developers interested in certain technical areas.

Some overlap, some links between technologies might be missing, some documentation could be more discoverable, some documentation is dispersed across several websites, sometimes we lack documentation, sometimes we have too much documentation, sometimes our documentation is outdated.

Goal
Create and establish a central entrance point which lists all relevant documentation about technical areas of Wikimedia's ecosystem, targeting existing and future developers of Wikimedia software projects, and developers interacting via code with Wikimedia software projects or Wikimedia hosted services and data.

The main intention of this initiative is funneling and allowing everyone replying to questions where to find developer documentation to ideally point to one single entrance point.

Furthermore, many organizations and companies host single developer portals. There must be some reason. ;)

Ideally, the portal should allow developers to:
 * Discover available tools and technologies
 * Learn how to get started in Wikimedia technical areas
 * Find documentation how to achieve a certain task

Scope

 * Primarily a link hub with a collection of links to existing documentation.
 * Keep it high-level: ideally, one page per area or use case to be linked.
 * The audience is existing and future developers of Wikimedia software projects or interacting via code with Wikimedia software projects or Wikimedia hosted services and data (means: not targeting end users, translators, sysadmins). To be further defined.
 * Writing separate new docs is out of scope (not against it, but not planned as part of this initiative).
 * Moving content around is out of scope (not against it, but not planned as part of this initiative).

Planning
This timeline is high level and subject to change:
 * Financial Year 2020‒21: Focus on research, feedback, and getting a bigger picture of the technical documentation situation
 * Jul 2020‒Sep 2020: Announce project; set up wiki page
 * Oct 2020‒Dec 2020: First iteration: Explorative conversations conversations with stakeholders (WMF) to identify use cases and key technical documents, understand workflows, gather technology areas
 * Jan 2021‒Mar 2021: Second iteration: Research and conversations with stakeholders (broader community): Gather technology areas and existing docs
 * Apr 2021‒Jun 2021: Review portals of other organizations; Define top-level categories and structure
 * ≥Apr 2021: Identify "key technical documents" linked from the portal; define process and ownership to keep documentation organized and up-to-date; identify concrete potential improvements
 * Financial Year 2021‒22:
 * ≥Jul2021: Implementation of portal as the key entrance point (navigation, hosting, etc)

See the Wikimedia-Developer-Portal project in Phabricator and its workboard for a breakdown of tasks per quarter and more details. (See Phabricator/Help for general information about Phabricator.)

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, random Wikimedia related technology, home of some engineering teams' pages)
 * 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 team pages)
 * https://wikitech.wikimedia.org (Wikimedia infrastructure/servers/network, Toolforge and Cloud VPS, Analytics)
 * https://doc.wikimedia.org (API references for classes) (technical details on content generation)
 * https://meta.wikimedia.org (less technical; mostly cross-Wikimedia movement stuff for coordination and planning, 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.