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 2021: Correctness checks of content linked from the prototype
 * ≥Jan 2022: Investigate requirements for the technical implementation of a single entrance point, based on the prototype
 * ≥Jan 2022: Conversations on potential improvement of processes around key technical documents (structure, locations, navigation, stewardship, etc), by potentially utilizing the Documentation/Maturity model for MediaWiki technical documentation to improve practices and processes.

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.

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)