Add an overview page for the Paint Timing API (mdn#20346)

* Add an overview page for the Paint Timing API Fixes mdn#10287 * Apply suggestions from code review Co-authored-by: Jean-Yves Perrier <[email protected]>
himanshugarg · Sep 27, 2022 · 1366f35 · 1366f35
1 parent 63bf17c
commit 1366f35
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 8 deletions.
diff --git a/files/en-us/glossary/first_contentful_paint/index.md b/files/en-us/glossary/first_contentful_paint/index.md
@@ -13,5 +13,8 @@ _The First Contentful Paint_ time stamp is when the browser first rendered any t
 
 ## See also
 
-- [First Meaningful Paint](/en-US/docs/Glossary/first_meaningful_paint)
-- [Paint Timing specification](https://w3c.github.io/paint-timing/#first-contentful-paint)
+- [First paint](/en-US/docs/Glossary/First_paint)
+- [Paint Timing API](/en-US/docs/Web/API/Paint_Timing_API)
+- [Largest Contentful API](/en-US/docs/Web/API/Largest_Contentful_Paint_API)
+- [First meaningful paint](/en-US/docs/Glossary/first_meaningful_paint)
+- [First Contentful Paint](https://web.dev/fcp/) at web.dev
diff --git a/files/en-us/glossary/first_paint/index.md b/files/en-us/glossary/first_paint/index.md
@@ -7,10 +7,11 @@ tags:
   - Performance
   - Web Performance
 ---
-**First Paint**, part of the [Paint Timing API](/en-US/docs/Web/PerformancePaintTiming), is the time between navigation and when the browser renders the first pixels to the screen, rendering anything that is visually different from what was on the screen prior to navigation. It answers the question "Is it happening?"
+**First Paint**, part of the [Paint Timing API](/en-US/docs/Web/API/Paint_Timing_API), is the time between navigation and when the browser renders the first pixels to the screen, rendering anything that is visually different from what was on the screen prior to navigation. It answers the question "Is it happening?"
 
 ## See also
 
-- [First meaningful paint](/en-US/docs/Glossary/first_meaningful_paint)
 - [First contentful paint](/en-US/docs/Glossary/First_contentful_paint)
-- [Paint Timing API](/en-US/docs/Web/PerformancePaintTiming)
+- [Paint Timing API](/en-US/docs/Web/API/Paint_Timing_API)
+- [Largest Contentful API](/en-US/docs/Web/API/Largest_Contentful_Paint_API)
+- [First meaningful paint](/en-US/docs/Glossary/first_meaningful_paint)
diff --git a/files/en-us/web/api/largest_contentful_paint_api/index.md b/files/en-us/web/api/largest_contentful_paint_api/index.md
@@ -4,18 +4,24 @@ slug: Web/API/Largest_Contentful_Paint_API
 page-type: web-api-overview
 tags:
   - API
+  - Largest Contentful Paint API
   - LargestContentfulPaint
+  - Landing
   - Overview
   - Reference
   - Experimental
 browser-compat: api.LargestContentfulPaint
 ---
 {{DefaultAPISidebar("Largest Contentful Paint API")}}{{SeeCompatTable}}
 
-The **Largest Contentful Paint (LCP) API** enables monitoring the largest paint element triggered on screen.
+The **Largest Contentful Paint API** provides [perceived performance](/en-US/docs/Learn/Performance/Perceived_performance) data that allows you to know exactly how long a user waits, after navigating to your page, before seeing the main content of the page in their browser viewport — in contrast to just knowing when the user can first see a loading indicator or background image or other such initial/early-loading content (which is what the related [Paint Timing API](/en-US/docs/Web/API/Paint_Timing_API) provides).
 
 ## Concepts and Usage
 
+The key principle underlying the Largest Contentful Paint API is that by having data to help you minimize the time that users have to wait before they can see the site's main content, you can make the site feel more engaging and responsive (better performing) for your users.
+
+See the [perceived performance](/en-US/docs/Learn/Performance/Perceived_performance) article for an introduction to the core concepts underlying both the Largest Contentful Paint API and the [Paint Timing API](/en-US/docs/Web/API/Paint_Timing_API).
+
 The Largest Contentful Paint metric provides the render time of the largest image or text block visible within the viewport, recorded from when the page first begins to load. The API supports the following elements:
 
 - {{HTMLElement("img")}} elements.
@@ -57,5 +63,8 @@ observer.observe({entryTypes: ['largest-contentful-paint']});
 
 ## See also
 
-- [Largest Contentful Paint (LCP)](https://web.dev/lcp/)
-- [LCP in Lighthouse](https://web.dev/lighthouse-largest-contentful-paint/)
+- [Perceived performance](/en-US/docs/Learn/Performance/Perceived_performance)
+- [Largest Contentful Paint](https://web.dev/lcp/) at web.dev
+- [Optimize Largest Contentful Paint](https://web.dev/optimize-lcp/) at web.dev
+- [User-centric performance metrics](https://web.dev/user-centric-performance-metrics/#types-of-metrics) at web.dev
+- [Largest Contentful Paint in Lighthouse](https://web.dev/lighthouse-largest-contentful-paint/)
diff --git a/files/en-us/web/api/paint_timing_api/index.md b/files/en-us/web/api/paint_timing_api/index.md
@@ -0,0 +1,50 @@
+---
+title: Paint Timing API
+slug: Web/API/Paint_Timing_API
+page-type: web-api-overview
+tags:
+  - API
+  - Paint Timing API
+  - Performance
+  - PerformancePaintTiming
+  - Landing
+  - Overview
+  - Reference
+browser-compat: api.PerformancePaintTiming
+---
+{{DefaultAPISidebar("Paint Timing API")}}
+
+The **Paint Timing API** provides [perceived performance](/en-US/docs/Learn/Performance/Perceived_performance) data that allows you to know exactly how long a user waits, after navigating to your page, before seeing any of the page content at all (which may not yet be the main content) first starting to appear. More specifically, it allows you to know exactly when, during page load, {{Glossary("first paint")}} and {{Glossary("first contentful paint")}} occur.
+
+The [Largest Contentful Paint API](/en-US/docs/Web/API/Largest_Contentful_Paint_API) is a closely-related API that allows you to know exactly how long a user waits before they can see the **main content** of your page in the browser viewport — in contrast to just knowing when the user can see what may be a loading indicator or background image or other such initial/early-loading content (which is what the Paint Timing API provides).
+
+## Concepts and usage
+
+The key principle underlying the Paint Timing API is that by having data to help you minimize the time that users have to wait before they can see the site's content start to appear, you can make the site feel more engaging and responsive (better performing) for your users.
+
+See the [perceived performance](/en-US/docs/Learn/Performance/Perceived_performance) article for an introduction to the core concepts underlying both the Paint Timing API and the [Largest Contentful Paint API](/en-US/docs/Web/API/Largest_Contentful_Paint_API).
+
+## Interfaces
+
+- {{domxref('PerformancePaintTiming')}}
+  - : Extends the {{domxref('PerformanceEntry')}} interface with the additional {{domxref('PerformanceEntry.entryType', 'entryType')}} value `"paint"` and the two additional {{domxref('PerformanceEntry.name', 'name')}} values `"first-paint"` and `"first-contentful-paint"`.
+
+## Examples
+
+See the {{domxref('PerformancePaintTiming')}} article for an example of using the Paint Timing API.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [First paint](/en-US/docs/Glossary/First_paint)
+- [First contentful paint](/en-US/docs/Glossary/First_contentful_paint)
+- [Largest Contentful API](/en-US/docs/Web/API/Largest_Contentful_Paint_API)
+- [Perceived performance](/en-US/docs/Learn/Performance/Perceived_performance)
+- [User-centric performance metrics](https://web.dev/user-centric-performance-metrics/#types-of-metrics) at web.dev
diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json
@@ -739,6 +739,13 @@
       "properties": ["indexedDB"],
       "events": []
     },
+    "Largest Contentful Paint API": {
+      "overview": ["Largest Contentful Paint API"],
+      "interfaces": ["LargestContentfulPaint"],
+      "methods": [],
+      "properties": [],
+      "events": []
+    },
     "Layout Instability API": {
       "overview": ["Layout Instability API"],
       "interfaces: ": ["LayoutShift", "LayoutShiftAttribution"],
@@ -869,6 +876,13 @@
       "properties": ["Document.hidden", "Document.visibilityState"],
       "events": ["Document: visibilitychange"]
     },
+    "Paint Timing API": {
+      "overview": ["Paint Timing API"],
+      "interfaces": ["PerformancePaintTiming"],
+      "methods": [],
+      "properties": [],
+      "events": []
+    },
     "Payment Request API": {
       "overview": ["Payment Request API"],
       "guides": [