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

The goal of this research is to understand the current state of the docs of the MediaWiki Action API, improvements needed, and then make some recommendations for next steps:

Documentation issues with MediaWiki Action API
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

 * 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.

Specific details about the API:Main_page

 * 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