Developer Advocacy/Developer Portal
This page is currently a draft.
"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
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.
Create an organization strategy for identifying and maintaining key documentation, and establish a central place which lists all entrance points to relevant documentation about technical areas of Wikimedia's ecosystem. Target groups are 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 place.
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
- 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).
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 (phab:T260984; phab:T260897)
- Jan 2021‒Mar 2021: Second iteration: Research and conversations with stakeholders (broader community): Gather technology areas and existing docs (phab:T260985)
- Apr 2021‒Jun 2021: Review portals of other organizations (phab:T260987); 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)
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#Blueprint (2012)
- phab:T67074 (2014-2015) - "Set up dev.wikimedia.org portal"
- Web APIs hub (2013-2015); see phab:T308/phab: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)
- phab: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)
- 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://meta.wikimedia.org/wiki/Tech (as a portal split, recommended by meta:Small wiki toolkits)