User:SSethi (WMF)/Sandbox/Investigate and improve MediaWiki Action API docs

From mediawiki.org

This document contains research on the state of the docs of MediaWiki Action API, suggests recommendations for next steps and lists work already in progress related to improving the docs:

Target for Q1, July-September 2018[edit]

Massviews analysis of pages under Category:MediaWiki_Action_API gives some idea of which API pages are viewed more frequently. For Q1:July-September2018, the target is to focus on the first twenty commonly viewed pages. These pages include documentation of 7-8 API modules and rest are overview pages (such as Errors and warnings, Etiquettes, etc.). So, we are planning to improve the documentation of 7-8 API modules and API:Main_page and all the pages it covers.

Research on the state of the docs of MediaWiki Action API[edit]

Both the abstract and concrete details in the sections below reflect the issues with the current state of the MediaWiki Action API:

The big picture[edit]

  • The MediaWiki Action API supports not just querying but also a lot of other actions like authenticating, searching, changing content on Wiki. Though, the API's main page links to documentation of other modules, it is not highlighted well what the capabilities of MediaWiki Action API are.
  • There are several other Wikimedia APIs linked from the API:Main_page (e.g., Rest API, Wikidata API, Commons API, etc.). It is not clear what would be the advantage of choosing one over another. On other note, we do not need to publicize other APIs here.
  • Some parts of the Action API doc explains a concept using another Wikimedia API (e.g. Rest API or MediaWiki core internal API) which is confusing.
  • It is not apparent which is the central hub for Action APIs. Somewhat similar pages show up in the Google results:
    • API:Main_page - It seems to be the hub of MediaWiki action APIs, but the page name does not reflect the same.
    • API:Tutorial - This is about the REST API.
    • API:Web_APIs_hub - It seems to be the hub of all Wikimedia APIs, but the page name does not reflect the same, nor it lists all the Wikimedia APIs.
    • API:Query - It is about one query module which is supported by the Action API.
  • Action APIs modules docs (API:Query, API:Login, API:Block, etc.) lacks sample code. Though, there are code samples in a few; they are inconsistent and written in different languages.
  • The content for individual actions supported by API sometimes mixes the audience: wiki administrators, library developers, API users, extension developers, etc.

Specific details about the API:Main_page[edit]

  • Page name does not reflect that API:Main_page is the hub for the MediaWiki Action APIs
  • The menu bar on the right displays an input box and a search button below it. It is not clear if they are related. Perhaps, we only need one. The actions in the menu are not categorized well and seem to be mixed up with some of the other page links such as FAQ’s, introduction, etc.
  • Introduction section
    • Two prominent notices in gray box need language work - the first one about internal API can be a bit clearer and the other one more newcomer-friendly.
    • There could be a separate section about the web clients examples.
    • Give more context on the outward facing interfaces; why they are mentioned here.
    • The point about restricting the use of API does not go well here - it is perhaps for API developers or administrators and could be left in a note separately.
  • A simple example section
    • Needs style improvement
    • All action parameters, format, endpoints could be in a table format
    • Add an example of fetching the content of a Wikipedia page via a programming language like Python
    • Explanation of the RSD format is not clear
  • FAQ document is incomplete and mostly about the errors related to Action API
  • Getting started section - there is some overlap in the information contained in the three docs linked from here: FAQ, errors and warnings and data formats
  • Identifying your client section - the sample code in there is confusing. For example, it uses MediaWiki internal API (mw.API) to demonstrate how to fetch data and it could be unclear to users who are not familiar with it
  • Query module is highlighted in the overall document but not some of the other modules supported by the API
  • Logging section can be removed
  • Useful links could be split into sections: a place to report bugs, contact, API documentation, etc.
  • Other Action API subpages that needs improvement
    • API:Properties and subpages
    • API:Query and subpages
    • API reference
    • API:Data formats
    • API:FAQ
    • API:Errors and Warnings
    • API:Tutorial
    • API:Client code
    • API:Etiquette

Recommendations for next steps[edit]

  • Add code samples for individual actions supported by the API (e.g. API:Edit, API: Login, etc.)
    • Explore some other API docs (Twitter, FB, etc)
    • Design a consistent writing style format for each action page. It could contain:
      • Short description of what the API does
      • API endpoints / Web hooks
      • Link to try the API in a Sandbox
      • Parameters
      • Replace on-wiki API documentation with Special:ApiHelp transclusion Phab:T89318
      • Possible errors
  • Make a list of all the actions supported by the Action API and re-categorize them in the right menu on API:Main_page
  • Improve the writing style and discoverability of API:Main_page / main hub for Action API
  • Give a better explanation of when to use Action APIs; pros or cons of using them over some of the other APIs in the Wikimedia universe
  • Overall review and make improvements to all the docs that are in the MediaWiki Action API category

Work in progress[edit]

Phase 1[edit]

Sandbox to Mainspace migration steps:

  • Some more pages (top 20 most viewed) that could be reviewed/ improved:
    • API:Tutorial. Add ideas for demo apps:
      • Show nearby pages with images that have more red links (API:GeoSearch + API:Parsing_WikiText)
    • API:Query
    • API:Client code
    • API:Data formats
    • API:Properties
    • API:Error and warnings
    • API:Info
    • API:Edit
    • API:FAQ
    • API:Revisions
    • API:Categorymembers
    • API:Cross-site requests

Results[edit]

In the task description: https://phabricator.wikimedia.org/T198916

Retrieved from "https://www.mediawiki.org/w/index.php?title=User:SSethi_(WMF)/Sandbox/Investigate_and_improve_MediaWiki_Action_API_docs&oldid=2987428"