project

project copied to clipboard

This has been discussed in https://github.com/mdn/content/discussions/5121 and there's general agreement that something needs to be done, but no concrete proposal on the table. https://github.com/whatwg/fetch/pull/1392 will not be possible to document until this is resolved.

@teoli2003 can you label this proposed for Q3 2022?

Done!

This has been discussed in mdn/content#5121 and there's general agreement that something needs to be done, but no concrete proposal on the table. whatwg/fetch#1392 will not be possible to document until this is resolved.

@teoli2003 can you label this proposed for Q3 2022?

AFAIK there is a concrete proposal: https://github.com/mdn/content/discussions/5121#discussioncomment-785747 which is waiting for implementation. We talked about this the other day and thought it would be much easier to implement once we had page types for Web/API, which I think we will get done in the next few weeks (https://github.com/mdn/content/issues/16255).

cc @Rumyra .

Thanks for filing this OWD project proposal!

I'm a bit unclear what is the scope here. It would be nice if that could be clarified so I can then run this against the OWD prioritization criteria which guides us to make decisions.

• Is this asking us to do the page renaming project as per the MDN discussion?
• Or to solve the question how to document Response.prototype.json and a static Response.json on MDN/BCD?
• Something else?

(We do have page types now.)

Or to solve the question how to document Response.prototype.json and a static Response.json on MDN/BCD?

This is the motivating case, to make it possible to document these at the same time, in a pattern that can be followed by other cases in the future. Even if that's something unsightly like https://developer.mozilla.org/en-US/docs/Web/API/Response/json_static for now, I'd still consider this resolved.

Another problem here which isn't being addressed at the moment AFAIK is slugs: we need a way to have different URLs for static/instance methods/properties. Maybe either:

Response/
   Instance_methods
        /json
   Static_methods
        /json

or:

Response/
    /json
    /json_static

? I think I like the first better, but there's much more stuff in it.

Related BCD issue: https://github.com/mdn/browser-compat-data/issues/16613

Things we need for this to get done:

• merge https://github.com/mdn/yari/pull/7335
• merge another Yari PR, to make the sidebars understand short-title
• many automated PRs to rename Web/API pages along the lines of https://github.com/orgs/mdn/discussions/248#discussioncomment-3797416

The tricky bit left is slugs, since we've not discussed this yet. I expect we will end up with a _static suffix, which is a bit hacky but not too disruptive. We'd also need to update anything that expects slugs to have a particular form (sidebars again, at least).

One thing we have talked about is that these changes will make titles longer, so they will wrap more often (wrapping is already a problem for Yari). It would be great to have a design fix for this (e.g. auto scaling font size so it fits, and/or giving titles more width), but that would probably stop us getting this done in Q4.

Anything else?

See also https://github.com/orgs/mdn/discussions/264 (I wish GitHub added links for discussions).

Things we need for this to get done:

• [x] merge https://github.com/mdn/yari/pull/7335
• [x] merge another Yari PR, to make the sidebars understand short-title
• [x] definitive consensus on page titles, including l10n and any concerns around title length
• [x] many automated PRs to retitle Web/API pages
• [x] definitive consensus on slug changes: https://github.com/orgs/mdn/discussions/264
• [x] implement any page moves required by slug changes

Nice to see progress here! The new titles are great.

There's some cleanup to do still I think, e.g.

• https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly says "DOMRectReadOnly.x" as link text (maybe should be just "x"?)
• https://developer.mozilla.org/en-US/docs/Web/API/DOMMatrixReadOnly/flipX is listed as an instance method (should be static method)

Nice to see progress here! The new titles are great.

Thanks for the nice feedback!

There's some cleanup to do still I think, e.g.

• https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly says "DOMRectReadOnly.x" as link text (maybe should be just "x"?)

Yes, link text is a separate thing from titles and will take some thinking about. There's a mini-thread about this here: https://github.com/orgs/mdn/discussions/248#discussioncomment-4102050 .

I agree with you that in this context just the member name x is good, but in other contexts link text needs the interface name as well. For that lots of people like lowercasing the initial letter of the interface, like headers.append(), but cases like DOMRectReadOnly make this tricky to automate as we wouldn't want dOMRectReadOnly :). So there are things to work through here. But we will get there.

The next piece though, which is needed to support static and instance members with the same name, is to give them different URLs: https://github.com/orgs/mdn/discussions/264.

• https://developer.mozilla.org/en-US/docs/Web/API/DOMMatrixReadOnly/flipX is listed as an instance method (should be static method)

It doesn't seem to be, from the IDL: https://drafts.fxtf.org/geometry/#dommatrixreadonly , am I missing something?

I'm trying to understand what if anything we need to do about domxref here.

I think that after adding the _static suffix, existing domxref links will still work, because of redirects. So for instance: https://github.com/mdn/content/blob/f29d8a648ef7ada05a00c358bfb9e9f67f3bc90d/files/en-us/web/api/abortsignal/index.md?plain=1#L25 will still work, because https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/abort will redirect to https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/abort_static.

This does mean that if people ever make an "instance version" of one of the 42 currently existing static method/property, we will get errors.

For new statics, like https://github.com/mdn/content/issues/21550, people will need to call domxref like:

{{domxref("Response.json_static", "Response.json()")}}

...which is a bit ugly. We could add something to domxref that removes the _static suffix for the link text, so people can do something like:

{{domxref("Response.json()_static")}}

? @teoli2003 , wdyt, am I missing something here?

I think that after adding the _static suffix, existing domxref links will still work, because of redirects. So for instance: https://github.com/mdn/content/blob/f29d8a648ef7ada05a00c358bfb9e9f67f3bc90d/files/en-us/web/api/abortsignal/index.md?plain=1#L25 will still work, because https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/abort will redirect to https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/abort_static.

Yes, they will still work, but this will raise a flaw too (as it is a redirect)

This does mean that if people ever make an "instance version" of one of the 42 currently existing static method/property, we will get errors.

Yes, the redirect file will not like it and we will need to fix it. I don't expect this to happen, though.

If a non-static version of one of these 42 static members is ever created (and we fix the redirect file), the macros will then point to the non-static version.

For new statics, like mdn/content#21550, people will need to call domxref like:

{{domxref("Response.json_static", "Response.json()")}}

...which is a bit ugly. We could add something to domxref that removes the _static suffix for the link text, so people can do something like:

{{domxref("Response.json()_static")}}

We can add this, sounds like a good idea. Anyway, we need to fix the existing ones (we'll do this while fixing flaws), as if we create a non-static version in the future, they will suddenly point to the wrong page.

Macros are painful to maintain: regular links would "just" work and we'll have been automatically fixed already (yarn content move fixes regular MD links).