Talk:Documentation/API documentation/Landing page

Implementation notes

As I attempted to apply this doc structure to the Mediawiki REST API docs (phab:T405972) I encountered the following issues:

• Formatting: links to external (non-wiki) pages don't render well if used in the title-link field of the layout grid. This means the links must be put in the body of the box, like I did for the Tutorials box here. This makes the UX inconsistent for on-wiki resources linked on the landing page vs. off-wiki resources.
• Balance and content type: the example landing page I implemented mixes prose sections with navigation-focused layout sections. I feel unsure about this; it seems unbalanced, or like the reader would be better-served by a landing page that was clearly nav-focused or clearly content-focused, but not both. This would align more with our existing guidelines landing pages. Additional reflections about this issue relate to whether there's an Overview sub-page or how much overview and policy content can go on the landing page. See Talk:Documentation/API_documentation/Overview.
• Navigation from subpages and external resources: while the landing page provides nice access to subpages and external pages, I'm concerned about how disjointed the overall experience.
  • The Authorization instructions are in the OAuth docs; it doesn't seem wise to create a sharded subset of those instructions for a single API. But that means once you go to the auth guide, you're no longer in the same doc collection and can only get back via browser.
  • The tutorials are in PAWS notebooks which do link back to the API landing page, but still feel somewhat separate due to being in a different tool and UI. We'll encounter similar issues when linking to the in-development API sandbox, though at least it'll still be the same wiki UI even if it's a standalone Special page.
  • Once you navigate to a subpage, the lack of a consistent nav template across the collection means the only context indicator is breadcrumbs. I'm not sure if all MW skins show that. Maybe each subpage must have some sort of collection nav menu to ensure that the larger context and links are always visible?

TBurmeister (WMF) (talk) 16:06, 9 October 2025 (UTC)