This task captures work required to bring the MediaWiki REST API documentation into alignment with the standard documentation patterns defined as part of FY25/26 API and documentation strategy. It excludes work related to OpenAPI-based reference documentation, which is tracked separately (see parent and related tasks).
Baseline metrics and other content analysis details for this API doc collection are at: https://www.mediawiki.org/wiki/Wikimedia_Technical_Documentation_Team/API_documentation_strategy/Gaps#MediaWiki_REST_API
IA requirements:
- The API landing page supports navigation to each of the types of content required by the guidelines.
- The sequencing of information in the navigation menu follows the sequence outlined in the guidelines.
- The overview information on the landing page previously included some how-to content mixed in with access policy info. The Client Identification and Authorization info in this section was revised and split into a separate guide. It was previously confusing that there are two sections about authorization (more about this below).
- Before: The use of a nav menu to link to important subpages, but putting all overview and quick-start content on the landing page is creating a doc UX that feels somewhat unbalanced; I think it would be better to reduce the prose on the landing page and give more prominence to links to the very important subpages, and reconsider whether some of the content like the "Conditional requests" page should be integrated into other content. It's also unclear how prominent the Extension and CORS content should be, but right now all the links seem to have equal prominence, which I don't think reflects their usage or importance.
- After: The landing page is primarily navigation-focused but retains come key information in prose; quick start content is moved to getting started guide. Nav menu updated to reflect the same content structure as the landing page. Conditional requests integrated into Getting started guide.
- Each content page (including sandbox/explorer UI) supports navigation back to the API's landing page.
- Before: https://www.mediawiki.org/wiki/Template:REST_API is not on all pages in the collection: https://www.mediawiki.org/wiki/API:REST_API/Reference uses a different navigation box.
- After: https://www.mediawiki.org/wiki/Template:REST_API is on all possible pages, and API:REST_API/Reference no longer has a separate nav section of its own.
Content requirements:
- The API doc collection has a landing page that includes each piece of content specified in the guidelines.
- Before: Landing page includes all overview content and links to tutorials and reference. The page could benefit from being refactored and the overview content expanded.
- After: Overview content expanded, quick start and access / usage + stability policy content moved to new subpages.
- The API overview section or page covers the minimum required content.
- Done: Expand overview content to cover more of this APIs features, and why one would use it instead of the other APIs (user question).
- Done: Address the confusing presence of two sections on authorization (see more below).
- The API doc collection includes a quick start tutorial.
- The API doc collection includes an authentication how-to guide.
- Done: Addressed the confusion of having two sections: one for "Permissions and Authorization" and one for "Authorization". The latter previously linked to https://www.mediawiki.org/wiki/Special:MyLanguage/OAuth/For_Developers. We should explore if there's a way to avoid asking the reader to read the entire Oauth guide for developers, and instead provide the relevant info within a small authorization how-to guide. T349790 tracks work to improve the UX of the OAuth documentation in general.
- The API doc collection includes recipes or real-world examples for common tasks
- The API doc collection includes a changelog.
- Done: @KBach created https://www.mediawiki.org/wiki/API:REST_API/Changelog and it is linked from the landing page and stability policy section.
- The API's documentation content follows the Wikimedia documentation style guide.
- Done: Revise copy to use active voice and action-oriented headers/titles wherever possible