Page titles should reflect usage: crypto.getRandomValues instead of Crypto: getRandomValues()

[jakearchibald]

A big step forward was made in #8351, but I'd like to propose this rule to page naming:

1. If the item is available on the global, use the name. Eg:
   • ServiceWorkerGlobalScope.skipWaiting becomes skipWaiting.
2. If the item is typically reached via properties reachable from the global, use that property chain, omitting the global.
   • Document.querySelector becomes document.querySelector.
   • CacheStorage.match becomes caches.match.
3. If the item is an instance method/property, use the constructor name with the first set of caps lower-cased + the property name.
   • Element.getBoundingClientRect becomes element.getBoundingClientRect.
   • HTMLElement.offsetHeight becomes htmlElement.offsetHeight.
4. If the item is a static method/property, use the constructor name + the property name.
   • Notification.requestPermission remains Notification.requestPermission.
5. Otherwise, just use the name.
   • PointerEvent remains PointerEvent

[Elchi3]

Thanks Jake!

You didn't mention what to do if the item is a static method/property. Luckily this (and more on titles) was discussed and answered here: https://github.com/mdn/content/discussions/5121#discussioncomment-785747

[jakearchibald]

I've added a step for static methods/properties.

[Josh-Cena]

I believe this is already completed.

[jakearchibald]

I still think this could be better.

For example: https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues - it isn't until the example that you discover this can be called via self.crypto.getRandomValues.

The steps I provided in the OP would have titled this page crypto.getRandomValues, which is how you call this API.

[Josh-Cena]

We now recommend large-scale suggestions to be tracked separately (because the traffic here is huge), so further improvements could be discussed within https://github.com/mdn/mdn-community or https://github.com/mdn/mdn.

Regardless, I'm ambivalent: while crypto.getRandomValues() is probably the only way developers can meaningfully interact with Crypto, is crypto actually meant to be a singleton? This question applies to all other interfaces that have a global instance.

[jakearchibald]

further improvements could be discussed within https://github.com/mdn/mdn-community or https://github.com/mdn/mdn.

Which is best for this topic?

is crypto actually meant to be a singleton?

Yes. Where else do you see instances of Crypto?

This question applies to all other interfaces that have a global instance.

It doesn't. That's why I made the distinction in the OP "If the item is typically reached via properties reachable from the global"

https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues - Right now, if I wanted to find out how to use getRandomValues, MDN buries key information in the example, which is way down the page. Information of how to access the function shouldn't appear way after it's params, return value etc etc. It feels like developers are likely to land on this page because they want to know how to call this function. MDN doesn't currently cater well for this use-case.

https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register - Right now, if I wanted to find out how to register a service worker, MDN buries key information in the example, which is way down the page. Information of how to access the function shouldn't appear way after it's params, return value etc etc. It feels like developers are likely to land on this page because they want to know how to register a service worker. MDN doesn't currently cater well for this use-case.

https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined - Right now, if I wanted to find out when a custom element is defined, MDN buries key information in the middle of the second and final example, which is at the end of the content. Information of how to access the function shouldn't appear way after it's params, return value etc etc. It feels like developers are likely to land on this page because they want to know how tell when a custom element is defined. MDN doesn't currently cater well for this use-case.

As a counter-example, history.pushState states how to access the method early in the article https://developer.mozilla.org/en-US/docs/Web/API/History/pushState.

I can provide more examples if needed, but I'd hope that MDN aimed to hit these use-cases, and wouldn't be ambivalent to these kinds of failures.

[Josh-Cena]

Okay, I'm going to reopen this. cc @mdn/yari-content-web-api for further discussions