Developer Advocacy/Developer Portal

From mediawiki.org
Jump to navigation Jump to search

Problem[edit]

"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[edit]

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

Scope[edit]

  • 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[edit]

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)

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[edit]

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.

Existing high-level entry points[edit]

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.