Make User Timing overview page more overviewy

[Elchi3]

Description

This PR wants to make the https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API overview page better, or rather, less verbose and more overviewy.

Motivation

I'd like a better understanding what an overview page is exactly and what it should contain, so I'm re-arranging this one.
I want it to be distinct from the "Using ..." page.

Also, openwebdocs/project#62

Additional details

So, to me, the structure of an overview page is this:

• Intro sentence that describes the purpose of the whole API and what to do with it
• Ideally a short example that is very typical for this API
• Lists of all the guide pages for this API
• Lists of all the reference pages of this API
• Other important info
• Maybe a compat table, but this is tricky
• See also

It is all very short and not rich in text. I see it as a cheatsheet or as a helper to navigate through all pages for this API.

It is a bit sad we don't have any styled page components. So I think my choices are lists (done here), or tables (ugly in md). I think tables arrange content nicely sometimes (example), however I didn't feel like using them here. Let me know if you have other ideas.

Related issues and pull requests

What are your favorite overview pages?

[github-actions]

Preview URLs

• /en-US/docs/Web/API/User_Timing_API

External URLs (1)

URL: /en-US/docs/Web/API/User_Timing_API
Title: User Timing API

• https://w3c.github.io/user-timing/ (1 time) (Note! This may be a new URL 👀)

(this comment was updated 2022-10-31 08:44:14.283185)

[wbamberg]

FWIW I think these pages have quite a well-defined structure, and a template even, at https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_landing_page_template.

I think they have:

• a moderately short intro
• an H2 "Interfaces" that lists the interfaces the API defines
• an H2 "Specifications" section. I think this is quite important because these pages usually map to a single specification which in this case is https://w3c.github.io/user-timing/.

BCD I agree is problematic and I don't know what is best here. Different pages do different things. See https://github.com/mdn/content/discussions/4920 .

I agree that the current page is much too chatty and a lot of it should be in "Using the...".

[Elchi3]

FWIW I think these pages have quite a well-defined structure, and a template even, at https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_landing_page_template.

Ah, thanks for the pointer!

• an H2 "Interfaces" that lists the interfaces the API defines

I think I've shortened this quite a lot now so that it briefly lists what you can do with the two main interfaces. Actually, I think listing things you can to do with the interfaces at hand seems useful and more practical than listing things under "interfaces" and "Extension to other interfaces" (per the template) which seems like less practical info and like more like API design concerns.
If I come to an overview page for an API, I think I want answers for: What is this API? What sort of tasks can I get done with it? So, on this overview page there are a few headings for tasks you can do, and then there are reference page pointers to the interfaces/methods/things that allow you to do a task.

• an H2 "Specifications" section. I think this is quite important because these pages usually map to a single specification which in this case is https://w3c.github.io/user-timing/.

Added a Specifications section with a link to the spec. Wasn't sure how to have generate a spec table for the whole API (and not a particular feature).

BCD I agree is problematic and I don't know what is best here. Different pages do different things. See #4920 .

I didn't add any BCD table. Seems fine given it is well supported.

I agree that the current page is much too chatty and a lot of it should be in "Using the...".

👍

[jpmedley]

Florian,

This is really clean of typos. Since this PR is about improving the piece over all, I thought you might be interested in a few language improvements.

Joe

[hamishwillee]

@wbamberg Fly by re #21853 (comment)

FWIW I think these pages have quite a well-defined structure, and a template even, at https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_landing_page_template.

FWIW I think I've been guilty of copying the "big overview" pattern with user guide material. Sometimes it feels like it makes sense - or alternatively, that spawning a "Using guide" for a simple example feels like pointless indirection.

What I find interesting about the template is that you should almost be able to generate the overview as defined from the API data used to create the sidebar.

[Elchi3]

Will and I think that this page isn't needed, because all you really need is an overview of all the Performance APIs and a guide that explains how to use them (together, and not separately). So, I think this PR is an improvement but it is likely we will redirect this page to https://developer.mozilla.org/en-US/docs/Web/API/Performance_API once we made that main Performance API page better (#21984).

I'm going ahead and merge this, so we have the improvements in, in case we decide to keep this page (or if parts of it are still useful later).

All comments addressed

[Elchi3]

Ah well, turns out I need 1 approving review. :)

[wbamberg]

What I find interesting about the template is that you should almost be able to generate the overview as defined from the API data used to create the sidebar.

Oh I just saw this. Yes. I want this to be one of our infra goals. Not all the overview but lots of it.

[wbamberg]

Ah well, turns out I need 1 approving review. :)

👍