[page types] Define page types for Web/API

[wbamberg]

Part of #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:

• api/arraybufferview
• api/buffersource
• api/canvasimagesource
• api/cssomstring
• api/domhighrestimestamp
• api/domstring
• api/domtimestamp
• api/epochtimestamp
• api/formdataentryvalue
• api/rtcstatsicecandidatepairstate
• api/rtcstatstype
• api/usvstring

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.

• api/ext_blend_minmax
• api/ext_color_buffer_float
• api/ext_color_buffer_half_float
• api/ext_disjoint_timer_query
• api/ext_disjoint_timer_query/beginqueryext
• api/ext_disjoint_timer_query/createqueryext
• api/ext_disjoint_timer_query/deletequeryext
• api/ext_disjoint_timer_query/endqueryext
• api/ext_disjoint_timer_query/getqueryext
• api/ext_disjoint_timer_query/getqueryobjectext
• api/ext_disjoint_timer_query/isqueryext
• api/ext_disjoint_timer_query/querycounterext
• api/ext_float_blend
• api/ext_frag_depth
• api/ext_shader_texture_lod
• api/ext_srgb
• api/ext_texture_compression_bptc
• api/ext_texture_compression_rgtc
• api/ext_texture_filter_anisotropic
• api/ext_texture_norm16
• api/khr_parallel_shader_compile
• api/oes_element_index_uint
• api/oes_fbo_render_mipmap
• api/oes_standard_derivatives
• api/oes_texture_float
• api/oes_texture_float_linear
• api/oes_texture_half_float
• api/oes_texture_half_float_linear
• api/oes_vertex_array_object
• api/oes_vertex_array_object/bindvertexarrayoes
• api/oes_vertex_array_object/createvertexarrayoes
• api/oes_vertex_array_object/deletevertexarrayoes
• api/oes_vertex_array_object/isvertexarrayoes
• api/ovr_multiview2
• api/ovr_multiview2/framebuffertexturemultiviewovr
• api/webgl_color_buffer_float
• api/webgl_compressed_texture_astc
• api/webgl_compressed_texture_astc/getsupportedprofiles
• api/webgl_compressed_texture_etc
• api/webgl_compressed_texture_etc1
• api/webgl_compressed_texture_pvrtc
• api/webgl_compressed_texture_s3tc
• api/webgl_compressed_texture_s3tc_srgb
• api/webgl_debug_renderer_info
• api/webgl_debug_shaders
• api/webgl_debug_shaders/gettranslatedshadersource
• api/webgl_depth_texture
• api/webgl_draw_buffers
• api/webgl_draw_buffers/drawbufferswebgl
• api/webgl_lose_context
• api/webgl_lose_context/losecontext
• api/webgl_lose_context/restorecontext
• api/webgl_multi_draw
• api/webgl_multi_draw/multidrawarraysinstancedwebgl
• api/webgl_multi_draw/multidrawarrayswebgl
• api/webgl_multi_draw/multidrawelementsinstancedwebgl
• api/webgl_multi_draw/multidrawelementswebgl

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.

• api/mscaching
• api/mscachingenabled
• api/mscandidatewindowhide
• api/mscandidatewindowshow
• api/mscandidatewindowupdate
• api/mscapslockwarningoff
• api/msfirstpaint
• api/msgestureevent
• api/msgetpropertyenabled
• api/msgetregioncontent
• api/msgraphicstrust
• api/msgraphicstruststatus
• api/msisboxed
• api/msmanipulationevent
• api/msmanipulationevent/initmsmanipulationevent
• api/msplaytodisabled
• api/msplaytopreferredsourceuri
• api/msplaytoprimary
• api/msplaytosource
• api/msputpropertyenabled
• api/msrangecollection
• api/msrealtime
• api/msregionoverflow
• api/mssetmediaprotectionmanager
• api/mssitemodeevent
• api/mssitemodejumplistitemremoved
• api/msthumbnailclick
• api/mswriteprofilermark

Misc

There are a few leftovers:

I think perhaps this useless page should be deleted?

• api/getcandidatewindowclientrect

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

• api/mediaconfiguration
• api/mediadecodingconfiguration
• api/videoconfiguration

[dontcallmedom]

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]

For the typedefs:

• api/cssomstring, api/domstring, api/usvstring: we are actively removing them:
  • CSSOMString – The only links left are in…DOMString, USVString, and itself. It is almost gone.(Remove USVString, DOMString and CSSOMString #17231)
  • USVString – Without counting DOMString, USVString, and itself, there are only 4 pages left linking to it. Consider it gone too(Remove USVString, DOMString and CSSOMString #17231)
  • DOMString – There are still 92 pages with them (initially we had more than 1000!), but Onkar is actively removing them. If needed, we can accelerate the movement here, but they will be gone this Quarter, if not this month.(Remove USVString, DOMString and CSSOMString #17231)
• api/domtimestamp, api/epochtimestamp, api/domhighrestimestamp: we want to replace them with number, and eventually an explanation (in seconds, in miliseconds, ev. obfuscated). They are the next targets after the string types.
  • DOMTimeStamp – 15 occurrences Delete DOMTimestamp and EpochTimestamp #17096
  • EpochTimeStamp – 1 single occurrence outside DomTimeStampand itself. Delete DOMTimestamp and EpochTimestamp #17096
  • DOMHighResTimeStamp – 96 occurrences (+ an overview page). This is a bit more work but on our radar.
• api/rtcstatsicecandidatepairstate (Merge RTCStatsIceCandidatePairState enum #17224), and api/rtcstatstype Delete RTCStatsType enum #17336.
  Like WebRTC dictionaries these are on our radar to be merged in the property and method pages using them.

The only ones to consider are:

• api/formdataentryvalue (2 occurrences except itself) Gone thanks to Update FormData and its method references #16965 and Delete FormDataEntryValue page #16967
• api/arraybufferview (34 occurrences) Remove ArrayBufferView typedef #17161
• api/buffersource (96 occurrences, the only problematic one) Remove BufferSource #17264
• api/canvasimagesource (10 occurrences) Remove CanvasImageSource typedef #17181

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]

For misc:

• Hamish deleted api/mediaconfiguration, api/mediadecodingconfiguration, api/videoconfiguration as part of FF101 AV1 codecs parsing  #15813 (In our movement to delete enums, typedefs and dictionaries, with maybe a few exceptions for the latest ones)
• api/getcandidatewindowclientrect: Let's delete it (I opened the PR: Delete empty getCandidateWindowClientRect page #16259).

[wbamberg]

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]

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]

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]

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?

(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]

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?

(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]

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]

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]

@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]

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