Add Web/API page types, part 1

[wbamberg]

This is part 1 of a series of PRs to add page types to the Web/API documentation.

This one is experimental, to see what it would look like. But if we like this I will file more like this, with 200 pages in each PR (about 30 PRs total to get through the set).

I've used the same page type names as in #16255, except lowercased and with dashes for spaces.

I'm going to ignore any pages that were identified as problematic in #16255.

It would be easy to do title updates and add short-title at the same time, maybe we should? But we would need a clear definition of all the titles and also updates to the sidebars (if we have short-title then these would be pretty simple though I think).

@Rumyra , @teoli2003 , @fiji-flo wdyt?

[OnkarRuikar]

If you are using tags to identify the page types then there are some mis-tagged pages. e.g. registerPaint (#16672 will fix this page).

We need to update the structure documents to include these.

• In future are we going to page-type the JavaScript pages too?
• Will it render existing page tags Method, Constructor, and Property redundant?

[wbamberg]

If you are using tags to identify the page types then there are some mis-tagged pages. e.g. registerPaint (#16672 will fix this page).

Yes, I know there are errors in tags. I'm not using tags. No doubt I have made some mistakes of my own though!

We need to update the structure documents to include these.

• In future are we going to page-type the JavaScript pages too?

Yes -> #15539

• Will it render existing page tags Method, Constructor, and Property redundant?

Yes. I think eventually, with various projects, we might well make all current tags redundant.

[teoli2003]

Technically, AddressErrors is not an interface but a dictionary. We want to get rid of dictionaries because their names are not visible to web devs. They are only objects.

I have no problem tagging them as interfaces for the moment.

[wbamberg]

Yes, I tagged these as interfaces after the discussion in #15539 (comment).

[teoli2003]

This is a dictionary (of a kind we want to keep, though)

[teoli2003]

This is a dictionary (of a kind we want to keep, though)

[teoli2003]

This is a dictionary (of a kind we want to keep, though)

[teoli2003]

This is a dictionary (of a kind we want to keep, though)

[teoli2003]

I'm approving, but not merging, to give everybody an opportunity to give feedback.

We have not discussed this, but you have considered dictionaries as interfaces. Generally, we want to get rid of dictionaries (like AddressErrors) as they are not visible to users (they are only unnamed objects). This is not always possible, or desirable, as sometimes they are large and used in numerous places (like the Crypto dictionaries and a couple of WebRTC dictionaries).

I have no problem in tagging them as interfaces for the moment.

It would be easy to do title updates and add short-title at the same time, maybe we should? But we would need a clear definition of all the titles and also updates to the sidebars (if we have short-title then these would be pretty simple though I think).

I would prefer to separate the different activities in different PRs: adding page-type YAML headers has no side effect; the other actions do not.

I think we should do this in 5 phases:

1. Adding page-type
2. Updating sidebars (APIRef and co) to rely on page-type instead of tags.
3. Deleting tags from Web/API
4. Updating API sidebars to deal with new page titles (Likely: if only title do as we do now, if sidebar-title, uses this one instead)
5. Update new page titles. (Likely: rename title to sidebar-title and add a new title, but this needs more checks!)

Points 1. to 3. are pretty clear, 4. to 5. still need some work. I prefer smaller contained steps than doing them all at the same time: less risky.

[Rumyra]

This looks good to me - I think the page types are intuitive.

Some other thoughts (which are out of scope for this pr but I'll put them here anyway):

• I think when we change page titles we should go with title and short-title rather than sidebar-title just because it's more generic and although I can't think of a use case now, there could be one in the future where we want a shorter title that isn't just for sidebars
• We should chat about updating the structure docs because I have some thoughts :)

[wbamberg]

This looks good to me - I think the page types are intuitive.

Some other thoughts (which are out of scope for this pr but I'll put them here anyway):

• I think when we change page titles we should go with title and short-title rather than sidebar-title just because it's more generic and although I can't think of a use case now, there could be one in the future where we want a shorter title that isn't just for sidebars

Thank you Ruth!

I agree that short-title is better. For instance some day an interface page might use it to list properties and methods.

I'll keep #15539 (comment) updated with a complete list of the page-type values, as we go.

[wbamberg]

I'm approving, but not merging, to give everybody an opportunity to give feedback.

We have not discussed this, but you have considered dictionaries as interfaces. Generally, we want to get rid of dictionaries (like AddressErrors) as they are not visible to users (they are only unnamed objects). This is not always possible, or desirable, as sometimes they are large and used in numerous places (like the Crypto dictionaries and a couple of WebRTC dictionaries).

I have no problem in tagging them as interfaces for the moment.

It would be easy to do title updates and add short-title at the same time, maybe we should? But we would need a clear definition of all the titles and also updates to the sidebars (if we have short-title then these would be pretty simple though I think).

I would prefer to separate the different activities in different PRs: adding page-type YAML headers has no side effect; the other actions do not.

I think we should do this in 5 phases:

1. Adding page-type

2. Updating sidebars (APIRef and co) to rely on page-type instead of tags.

3. Deleting tags from Web/API

4. Updating API sidebars to deal with new page titles (Likely: if only title do as we do now, if sidebar-title, uses this one instead)

5. Update new page titles. (Likely: rename title to sidebar-title and add a new title, but this needs more checks!)

Points 1. to 3. are pretty clear, 4. to 5. still need some work. I prefer smaller contained steps than doing them all at the same time: less risky.

We could also:

1. add page types
2. add short-title
3. update sidebars to use short-title and page types
4. update title
5. remove tags

...because sidebars should use short-title (and once sidebars are updated in (3), they won't care about title any more so we are free tp update it).

I think short-title should be exactly what we want to appear in the sidebar:

Page type	short-title
landing-page	same as title
guide	same as title
web-api-overview	same as title
web-api-global-function	function name with brackets, like fetch()
web-api-global-property	property name, like length
web-api-interface	interface name, like Request
web-api-constructor	function name with brackets, like Request()
web-api-instance-method	function name with brackets, like json()
web-api-instance-property	property name, like length
web-api-static-method	function name with brackets, like count()
web-api-static-property	property name, like length
web-api-event	event name, like click