first part, main interface, elememnttiming attribute

files/en-us/web/api/performanceelementtiming/index.md

@@ -13,12 +13,41 @@ browser-compat: api.PerformanceElementTiming
 
 {{APIRef("Performance API")}}{{SeeCompatTable}}
 
-The **`PerformanceElementTiming`** interface of the {{domxref('Element Timing API','','',' ')}} reports timing information on a specific element identified by the page author. For example it could report timing information about the main image in an article.
+The **`PerformanceElementTiming`** interface contains render timing information for image and text node elements the developer annotated with an [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute for observation.
+
+## Description
+
+The aim of the Element Timing API is to give web developers or analytics tools the ability to measure rendering timestamps of critical elements on a page.
+
+The API supports timing information on the following elements:
+
+- {{htmlelement("img")}} elements,
+- {{SVGElement("image")}} elements inside an {{SVGElement("svg")}},
+- poster images of {{htmlelement("video")}} elements,
+- elements which have a {{cssxref("background-image")}},
+- and groups of text nodes, such as a {{htmlelement("p")}}.
+
+The author flags an element for observation by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute on the element.
+
+`PerformanceElementTiming` inherits from {{domxref("PerformanceEntry")}}.
 
 {{InheritanceDiagram}}
 
 ## Instance properties
 
+This interface extends the following {{domxref("PerformanceEntry")}} properties for event timing performance entry types by qualifying them as follows:
+
+- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Always returns `0` as `duration` does not apply to this interface.
+- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Always returns `"element"`.
+- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns `"image-paint"` for images and `"text-paint"` for text.
+- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns the value of this entry's {{domxref("PerformanceElementTiming.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("PerformanceElementTiming.loadTime", "loadTime")}}.
+
+This interface also supports the following properties:
+
 - {{domxref("PerformanceElementTiming.element")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : An {{domxref("Element")}} representing the element we are returning information about.
 - {{domxref("PerformanceElementTiming.id")}} {{ReadOnlyInline}} {{Experimental_Inline}}
@@ -45,9 +74,9 @@ The **`PerformanceElementTiming`** interface of the {{domxref('Element Timing AP
 
 ## Examples
 
-In this example we have two elements which are being observed. We use the {{domxref("PerformanceObserver")}} interface to create a list of performance measurement events. In our case observing the {{domxref("PerformanceEntry.entrytype")}} `element` in order to use the `PerformanceElementTiming` interface.
+### Observing render time of specific elements
 
-Two entries will be output to the console. The first containing details of the image, the second with details of the text node.
+In this example two elements are being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation.
 
 ```html
 <img src="image.jpg" elementtiming="big-image" />
@@ -57,16 +86,22 @@ Two entries will be output to the console. The first containing details of the i
 ```js
 const observer = new PerformanceObserver((list) => {
   list.getEntries().forEach((entry) => {
-      console.log(entry);
+    console.log(entry);
   });
 });
-observer.observe({ entryTypes: ["element"] });
+observer.observe({ type: "element", buffered: true });
 ```
 
+Two entries will be output to the console. The first containing details of the image, the second with details of the text node.
+
 ## Specifications
 
 {{Specifications}}
 
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) HTML attribute

files/en-us/web/html/attributes/elementtiming/index.md

@@ -1,5 +1,5 @@
 ---
-title: 'HTML attribute: elementtiming'
+title: "HTML attribute: elementtiming"
 slug: Web/HTML/Attributes/elementtiming
 tags:
   - Attribute
@@ -12,7 +12,11 @@ tags:
 
 {{HTMLSidebar}}
 
-The **`elementtiming`** attribute is used to indicate that an element is flagged for tracking by the {{domxref("Element Timing API")}}. This attribute may be applied to {{htmlelement("img")}}, {{SVGElement("image")}} elements inside an {{SVGElement("svg")}}, poster images of {{htmlelement("video")}} elements, elements which have a {{cssxref("background-image")}}, and elements containing text nodes, such as a {{htmlelement("p")}}.
+The **`elementtiming`** attribute is used to indicate that an element is flagged for tracking by {{domxref("PerformanceObserver")}} objects using the `"element"` type. For more details, see the {{domxref("PerformanceElementTiming")}} interface.
+
+This attribute may be applied to {{htmlelement("img")}}, {{SVGElement("image")}} elements inside an {{SVGElement("svg")}}, poster images of {{htmlelement("video")}} elements, elements which have a {{cssxref("background-image")}}, and elements containing text nodes, such as a {{htmlelement("p")}}.
+
+In the DOM, this attribute is reflected as {{domxref("Element.elementTiming")}}.
 
 ## Usage
 
@@ -39,4 +43,5 @@ Good contenders for elements you might want to observe are:
 
 ## See also
 
-- [Custom metrics](https://web.dev/custom-metrics/)
+- {{domxref("PerformanceElementTiming")}}
+- {{domxref("Element.elementTiming")}}