search

mdn / content

The content behind MDN Web Docs
https://developer.mozilla.org
Other
9.2k stars 22.49k forks source link

[page types] Define page types for Web/API #16255

Closed wbamberg closed 1 year ago

wbamberg commented 2 years ago

Part of https://github.com/mdn/content/issues/15539.

In https://docs.google.com/spreadsheets/d/14RX8EEKPpeYkP2cF5Y_ZKF3JpNJ_24OL7stvZWNJLIY/edit#gid=2083448819, in the "API" tab, I've listed every page under https://developer.mozilla.org/en-US/docs/Web/API and made an initial determination about the page type.

I've come up with 12 types:

Web API overview (API)       119
Web API interface            896
Web API global function       11
Web API global property        6
Web API constructor          230
Web API instance method     1552
Web API instance property   2411
Web API static method         29
Web API static property        6
Web API event                433
Web API guide                202
Web API landing page           2

...and have ~100 unclassified.

The unclassified pages seem to fall into three main types: typdefs, WebGL extensions, and IE-only pages

typedefs

This includes the following:

Maybe we need a "typedef" type? But several of these, like DOMString we are trying not to use any more, as they don't seem useful, and perhaps some more, like RTCStatsIceCandidatePairState, could be removed.

WebGL extensions

These don't seem to fit into our Web API taxonomy at all. Maybe we need a WebGL extension type? Seems a shame though as it is rather specialised.

IE-only pages

These are all defined at the top level, which seems to be wrong in many cases. But I don't know which interfaces they should be attached to. And it's hard to want to spend much time digging into them.

Misc

There are a few leftovers:

I think perhaps this useless page should be deleted?

...and I think perhaps these were deleted in between me getting the list of pages and doing the analysis:

dontcallmedom commented 2 years ago

re WebGL extensions, from a quick check, they're actually interfaces (but whose interface object is not exposed to JavaScript); so maybe they could folded into interface pages?

what's the difference between an API overview and a landing page?

teoli2003 commented 2 years ago

For the typedefs:

The only ones to consider are:

They act as abbreviations for a list of interfaces. I think we should just rephrase the articles using them with that list...

So: I don't think we need the typedef page type, we should just finish the cleaning here.

teoli2003 commented 2 years ago

For misc:

wbamberg commented 2 years ago

re WebGL extensions, from a quick check, they're actually interfaces (but whose interface object is not exposed to JavaScript); so maybe they could folded into interface pages?

Thanks, that sounds plausible!

what's the difference between an API overview and a landing page?

A landing page is a generic page that presents lots of links to other pages, usually at the top of the IA for some content area. So for instance, https://developer.mozilla.org/en-US/docs/Web/CSS/Reference, https://developer.mozilla.org/en-US/docs/Web/API, https://developer.mozilla.org/en-US/docs/Web/HTML/Element are all landing pages. They don't have any defined structure (yet) so in that way are just like guide pages, and for our purposes now can can treat them just like guide pages. Although I think of them more like sidebars really.

An API overview page is specific to Web/API and describes an API, which generally (maybe always?) maps to a specification. It has a definite structure where we describe the API, list its interfaces and the specifications: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API.

Does that make sense?

teoli2003 commented 2 years ago

For the IE-specific pages, I would delete them (and redirect to their last GitHub version – I believe a good way to archive content now that we are using git). (And remove internal links leading to them).

That way we don't have to maintain them, but they are still available for IE-fanatics (a.k.a some product managers) victims out there.

wbamberg commented 2 years ago

For the IE-specific pages, I would delete them (and redirect to their last GitHub version – I believe a good way to archive content now that we are using git). (And remove internal links leading to them).

I think the main issue with the IE pages (apart from them being out of date) is that they are in the wrong place. That is, they are really attached to some interface, rather than being global. But it's hard to figure out which interface, given that there's so little information about them. So we could probably solve this, it's just whether it's worth it.

I would be OK to delete them as well. Redirecting to GitHub is a great idea we should totally do, but is not possible in content only as far as I know, so it's a dev dependency.

Also for these difficult cases I would be OK to not assign any page type for now, and that gives us a to-do list of unresolved pages while not blocking any work that depends on having page types.

teoli2003 commented 2 years ago

Redirecting to GitHub is a great idea we should totally do, but is not possible in content only as far as I know, so it's a dev dependency.

There are external redirects in _redirects.txt; I don't know if there is an allow-list or not, though. @schalkneethling do you know? Capture d’écran 2022-05-20 à 19 21 04

(I'm all for using GitHub as the archive of deleted content. It can even be the default if we don't specify a redirect when using yarn content delete.)

schalkneethling commented 2 years ago

Redirecting to GitHub is a great idea we should totally do, but is not possible in content only as far as I know, so it's a dev dependency.

There are external redirects in _redirects.txt; I don't know if there is an allow-list or not, though. @schalkneethling do you know? Capture d’écran 2022-05-20 à 19 21 04

(I'm all for using GitHub as the archive of deleted content. It can even be the default if we don't specify a redirect when using yarn content delete.)

Pining the engineering team for input here. /cc @mdn/core-dev

caugner commented 2 years ago

There are external redirects in _redirects.txt; I don't know if there is an allow-list or not, though. @schalkneethling do you know?

There is currently no restriction on external redirects.

schalkneethling commented 2 years ago

There are external redirects in _redirects.txt; I don't know if there is an allow-list or not, though. @schalkneethling do you know?

There is currently no restriction on external redirects.

Nice! Thank you for the feedback Claas 🙌

wbamberg commented 2 years ago

@dominiccooney suggested we should have dedicated page types for the WebGL pages, and I think this is best. I think this would give us two new page types:

webgl-extension
webgl-extension-method

(the second for extensions that add new methods, rather than extending existing methods.)

I'm going to file some PRs for this and see how it looks.

wbamberg commented 2 years ago

To help keep track of the MS pages I'm using a spreadsheet: https://docs.google.com/spreadsheets/d/1zN7PjWXDzWMtYNit86e6Fs1zDGZz8lCiXz_RoMFYU2c/edit?usp=sharing.