User:APaskulin (WMF)/Documentation Portal

Strategy

• Focus on learning and creating
• Frames things specifically in terms of Wikimedia, while mediawiki.org contains things that apply to the MediaWiki platform as a whole.
• Every page is page one.

APIs and Tools

Wikimedia API

In planning phase. Docs for this API will live in the portal only.

• Maintained by the Core Platform team

MediaWiki REST API

In development. Reference docs will be generated from the code and live in both the portal and mediawiki.org (to be implemented). Supporting docs for the MediaWiki REST API specific to its application for Wikimedia projects will live in the portal only. These docs will be replaced by the Wikimedia API once available.

• Maintained by the Core Platform team

Pageview API

These docs include a swagger spec and some wiki content. If team agrees, wiki content could be modified slightly to transclude into the portal.

• Maintained by the Analytics team
• Provides pageview data for Wikimedia projects
• Four endpoints using RESTBase (GET only)
• Pageviews tool: https://tools.wmflabs.org/pageviews
  • Source: https://github.com/MusikAnimal/pageviews
  • Meta-wiki page: https://meta.wikimedia.org/wiki/Pageviews_Analysis
• Wikitech page: https://wikitech.wikimedia.org/wiki/Analytics/AQS/Pageviews
  • Includes a quickstart section, access and back office details, client list, changelog, and a sample app
  • Sample app: https://gist.github.com/marcelrf/49738d14116fd547fe6d
  • Links to generated docs: https://wikimedia.org/api/rest_v1/
• JavaScript source: https://gerrit.wikimedia.org/g/analytics/aqs

Event Streams API

These docs include a swagger spec and some wiki content. If team agrees, wiki content could be modified slightly to transclude into the portal.

• Maintained by the Analytics team
• Provides access to a feed of recent changes for Wikimedia projects
• Wiki doc: https://wikitech.wikimedia.org/wiki/Event_Platform/EventStreams
• Generated docs (OpenAPI): https://stream.wikimedia.org/ (not rendering correctly)
• Example apps: https://wikitech.wikimedia.org/wiki/Event_Platform/EventStreams/Powered_By
• JavaScript source: https://gerrit.wikimedia.org/g/mediawiki/services/eventstreams
• Example code: https://codepen.io/ottomata/pen/VKNyEw/

ORES API

These docs include a swagger spec, some wiki content, and a static landing page. If team agrees, wiki content could be modified slightly to transclude into the portal.

• Maintained by the Scoring Platform Team
• Article quality and edit quality information
• Takes revision ids as arguments
• Project support: https://tools.wmflabs.org/ores-support-checklist/ (n/a?)
• MediaWiki.org page: https://www.mediawiki.org/wiki/ORES
• Generated docs (OpenAPI): https://ores.wikimedia.org/v3/#/scoring (old UI)
• Apps using ORES: https://www.mediawiki.org/wiki/ORES/Applications
• Python source: https://github.com/wikimedia/ores
• Web UI: https://ores.wikimedia.org/ui/
• Landing page: https://ores.wikimedia.org/

Action API

The docs for this API are pretty mature docs: automated reference alongside tutorials and intro content. We could incorporate the automated docs into the portal and adjust the styling to make them fit nicely; we could also transclude some of the tutorials as is. Although I'm hesitant to include this style of API in the portal, we could augment the existing docs by creating content aimed at less experienced developers. If team agrees, we could incorporate https://tools.wmflabs.org/apps-gallery/ into the portal.

• Maintained by the Core Platform team
• Provides content from any MediaWiki-based wiki, including Wikimedia projects and privately deployed MediaWikis
• Wiki docs: https://www.mediawiki.org/wiki/API:Main_page
  • https://www.mediawiki.org/wiki/API:Tutorial
• Generated docs: https://www.mediawiki.org/w/api.php?action=help
  • https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/core/+/master/includes/api/i18n/
• Sandbox: https://www.mediawiki.org/wiki/Special:ApiSandbox
• Example apps and generated sample code
  • https://tools.wmflabs.org/apps-gallery/
  • https://github.com/wikimedia/mediawiki-api-demos
• Tutorials
  • https://www.mediawiki.org/wiki/Special:MyLanguage/API:Article_ideas_generator
  • https://www.mediawiki.org/wiki/Special:MyLanguage/API:Nearby_places_viewer
  • https://www.mediawiki.org/wiki/Special:MyLanguage/API:Picture_of_the_day_viewer
  • https://www.mediawiki.org/wiki/Special:MyLanguage/API:Holidays_viewer
  • https://www.mediawiki.org/wiki/API:Presenting_Wikidata_knowledge
  • https://www.mediawiki.org/wiki/API:Page_info_in_search_results
• Admin info
  • https://www.mediawiki.org/wiki/API:Etiquette

REST API (RESTBase)

We've decided not to include this technology in the portal.

• Maintained by Core Platform team
• Provides content from Wikimedia projects
• Wiki doc: https://www.mediawiki.org/wiki/REST_API
• Generated docs (OpenAPI): https://en.wikipedia.org/api/rest_v1/
• Blog post: https://blog.wikimedia.org/2017/04/06/wikimedia-rest-api/

Data Dumps

This is a one of our primary use cases, so I would consider it a must-have for the portal. There are already a lot of good docs in meta that we may be able to pull in somewhat directly. We could also offer the portal as an option to get the content out of meta since there has been a general migration of technical content from meta to mediawiki.org. There is also a static site that could be imported if the team agrees.

• Content dumps maintained by SRE; there's a long tail of other dumps probably maintained by different teams
• Meta-wiki docs: https://meta.wikimedia.org/wiki/Data_dumps
  • https://meta.wikimedia.org/wiki/Data_dumps/Dumps_sizes_and_growth
• Landing page: https://dumps.wikimedia.org/
  • https://dumps.wikimedia.org/other/
• Wikitech docs: https://wikitech.wikimedia.org/wiki/Dumps
• Data page docs: https://meta.wikimedia.org/wiki/Research:Data#Data_dumps

Wikidata/SPARQL

This feeds into a portal on wikidata with really good content. I’d recommend not going too deep on this on the portal, maybe just a landing page with an example and link out to wikidata for all the learn-sparql bits.

• https://www.mediawiki.org/wiki/Wikidata_Query_Service/User_Manual#SPARQL_endpoint
• https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service/Wikidata_Query_Help
• https://www.mediawiki.org/wiki/Wikibase/API
• https://www.wikidata.org/wiki/Wikidata:Data_access
• https://www.mediawiki.org/wiki/API:Presenting_Wikidata_knowledge
• Example apps
  • https://tools.wmflabs.org/reasonator/?q=Q41469643
  • https://inventaire.io/entity/wd:Q535

Gadgets Index & OOUI Library

OOUI has well-organized docs, including a fancy static site and some generated docs. I think it would be better to link out to these docs, at least initially. There’s a great guide to creating user scripts in the English Wikipedia, so it could be a cool opportunity to pull that out into the portal and make it more accessible cross-projects if community agrees.

Gadgets

• In browser user scripts in CSS and JS
• https://en.wikipedia.org/wiki/Wikipedia:User_scripts/Guide
• https://www.mediawiki.org/wiki/Extension:Gadgets
• https://en.wikipedia.org/wiki/Wikipedia:Gadget

OOUI Library

• A library that allows developers to create responsive, accessible, cross-browser front-end web applications
• Wiki pages: https://www.mediawiki.org/wiki/OOUI
• Tutorials: https://doc.wikimedia.org/oojs-ui/master/demos/tutorials/index.html https://github.com/wikimedia/oojs-ui/tree/master/demos/tutorials
• Live preview and code editor: https://doc.wikimedia.org/oojs-ui/master/js/#!/api/OO.ui.Toolbar (could be losing this due to migration to jsDoc)

Supporting Content

• PAWS - Hosted Jupyter notebook environment: https://www.mediawiki.org/wiki/PAWS
  • http://paws-public.wmflabs.org/paws-public/User:Jtmorgan/ds4ux/paws-cheatsheet.ipynb
• https://foundation.wikimedia.org/wiki/Developer_app_guidelines

User Questions

From https://upload.wikimedia.org/wikipedia/commons/4/48/The_MediaWiki_Web_API_and_How_to_use_it_-_San_Francisco_Wikipedia_Hackathon_2012.ogv

• What are the limits for number of requests and amount of content returned?
• Do I need an API key?
• Can I get a dump of Wikipedia?
• Can I get a list of URLs where I can download Wikipedia page HTML files?
• How can I optimize my requests?
• How to get everything I want all in one place?
• How can I get the HTML content of a page?
• What types of requests are going to be resource intensive? What kind of performance can I expect?
• Can I make parallel requests?