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. ;)

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:
 * Jul 2020‒Sep 2020: Announce project; set up wiki page
 * Oct 2020‒Mar 2021: Have conversations with maintainers, developers, stakeholders: Gather technology areas and existing docs, collect use cases
 * Jan 2021‒Mar 2021: Review portals of other organizations
 * Apr 2021‒Jun 2021: Define top-level categories and structure
 * ≥Apr 2021: Identify "key technical documents" linked from the portal; define process and ownership to keep them well organized and up-to-date
 * ≥Jul2021: Implementation of portal (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)
 * 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 (mostly cross-Wikimedia movement stuff, random Wikimedia related technology, maybe home of some engineering teams' pages)
 * https://api.wikimedia.org/
 * Several external project-specific websites, e.g. https://wikiba.se, https://kiwix.org/, https://commons-app.github.io/, etc.