chore(http): Refresh headers docs (d-k)

files/en-us/glossary/forbidden_header_name/index.md

@@ -8,8 +8,18 @@ page-type: glossary-definition
 
 A **forbidden header name** is the name of any [HTTP header](/en-US/docs/Web/HTTP/Headers) that cannot be modified programmatically; specifically, an HTTP **request** header name (in contrast with a {{Glossary("Forbidden response header name")}}).
 
-Modifying such headers is forbidden because the user agent retains full control over them. Names starting with `Sec-` are reserved for creating new headers safe from {{glossary("API","APIs")}} that grant developers control over headers, such as {{domxref("Window/fetch", "fetch()")}}.
-
+Modifying such headers is forbidden because the user agent retains full control over them.
+For example, the {{HTTPHeader("Date")}} header is a forbidden header name, so this code cannot set the message `Date` field:
+
+```js example-bad
+fetch("https://httpbin.org/get", {
+  headers: {
+    Date: new Date().toUTCString(),
+  },
+});
+```
+
+Names starting with `Sec-` are reserved for creating new headers safe from {{glossary("API","APIs")}} that grant developers control over headers, such as {{domxref("Window/fetch", "fetch()")}}.
 Forbidden header names start with `Proxy-` or `Sec-`, or are one of the following names:
 
 - {{HTTPHeader("Accept-Charset")}}
@@ -26,8 +36,8 @@ Forbidden header names start with `Proxy-` or `Sec-`, or are one of the followin
 - {{HTTPHeader("Keep-Alive")}}
 - {{HTTPHeader("Origin")}}
 - {{HTTPHeader("Permissions-Policy")}}
-- `Proxy-`
-- `Sec-`
+- `Proxy-` headers
+- `Sec-` headers
 - {{HTTPHeader("Referer")}}
 - {{HTTPHeader("TE")}}
 - {{HTTPHeader("Trailer")}}

files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md

@@ -72,8 +72,15 @@ page-type: mdn-writing-guide
 
 {{httpsidebar}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}}
 
-The summary paragraph — start by naming the http header and saying what it does.
-This should ideally be one or two short sentences.
+The first sentence of the page must follow this format:
+
+> The HTTP **`header-name`** (header type) is used for X in Y circumstances.
+
+The 'header type' should say if it's a {{Glossary("request header")}}, a {{Glossary("response header")}}, or if it may be either.
+The summary paragraph should ideally be one or two short sentences.
+
+You can mention notable gotchas or common pitfalls in this section, linking to examples or more detailed documentation (guides, etc.) in this section.
+Two or three paragraphs in this section is appropriate, and if there are substantial usage notes to include, use a "Description" section after "Directives" below.
 
 <table class="properties">
   <tbody>
@@ -88,13 +95,13 @@ This should ideally be one or two short sentences.
     </tr>
     <tr>
       <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>yes or no</td>
+      <td>"Yes" or "No"</td>
     </tr>
     <tr>
       <th scope="row">
         {{Glossary("CORS-safelisted response header")}}
       </th>
-      <td>yes or no</td>
+      <td>"Yes" or "No"</td>
     </tr>
   </tbody>
 </table>
@@ -123,13 +130,17 @@ Multiple directives are comma-separated (delete information as appropriate).
 If the header has a lot of available directives,
 feel free to include multiple definition lists, subsections, and explanations as appropriate.
 
+## Description
+
+If there is too much content to include in the opening paragraphs, provide as much detail as necessary here, such as background information, hints for usage, and links to documentation.
+
 ## Examples
 
 Note that we use the plural "Examples" even if the page only contains one example.
 
 ### A descriptive heading
 
-Each example must have an H3 heading (`###`) naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
+Each example **must** have an H3 heading (`###`) naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
 See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples) for more information.
 
@@ -183,6 +194,8 @@ Developers can set and get HTTP headers using `fetch()` in order to provide appl
 ## See also
 
 Include links to reference pages and guides related to the current HTTP header. For more guidelines, see the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_.
+You can link to relevant response statuses like `\{{HTTPStatus("123", "123 Response Status")}}` and headers like `\{{HTTPHeader("Header-Name")}}`.
+You may group related statuses and headers in a single list item for brevity.
 
 - link1
 - link2

files/en-us/web/http/headers/accept-encoding/index.md

@@ -7,7 +7,7 @@ browser-compat: http.headers.Accept-Encoding
 
 {{HTTPSidebar}}
 
-The HTTP **`Accept-Encoding`** {{glossary("request header", "request")}} and {{glossary("response header")}} indicates the content encoding (usually a compression algorithm) that the recipient can understand.
+The HTTP **`Accept-Encoding`** {{glossary("request header", "request")}} and {{glossary("response header")}} indicates the content encoding (usually a compression algorithm) that the sender can understand.
 In requests, the server uses [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation) to select one of the encoding proposals from the client and informs the client of that choice with the {{HTTPHeader("Content-Encoding")}} response header.
 In responses, it provides information about which content encodings the server can understand in messages to the requested resource, so that the encoding can be used in subsequent requests to the resource. For example, this might be sent in the response to a `PUT` request to a resource that used an unsupported encoding.
 

files/en-us/web/http/headers/date/index.md

@@ -7,20 +7,7 @@ browser-compat: http.headers.Date
 
 {{HTTPSidebar}}
 
-The **`Date`** general HTTP header contains the date and time
-at which the message originated.
-
-> **Warning:** `Date` is listed
-> in the [forbidden header names](https://fetch.spec.whatwg.org/#forbidden-header-name)
-> in the fetch spec, so this code will not send the `Date` header:
->
-> ```js
-> fetch("https://httpbin.org/get", {
->   headers: {
->     Date: new Date().toUTCString(),
->   },
-> });
-> ```
+The HTTP **`Date`** {{Glossary("request header", "request")}} and {{Glossary("response header")}} contains the date and time at which the message originated.
 
 <table class="properties">
   <tbody>
@@ -33,7 +20,7 @@ at which the message originated.
     </tr>
     <tr>
       <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>yes</td>
+      <td>Yes</td>
     </tr>
   </tbody>
 </table>
@@ -46,29 +33,48 @@ Date: <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT
 
 ## Directives
 
-- \<day-name>
-  - : One of "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", or "Sun" (case-sensitive).
-- \<day>
-  - : 2 digit day number, e.g. "04" or "23".
-- \<month>
-  - : One of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct",
-    "Nov", "Dec" (case sensitive).
-- \<year>
-  - : 4 digit year number, e.g. "1990" or "2016".
-- \<hour>
-  - : 2 digit hour number, e.g. "09" or "23".
-- \<minute>
-  - : 2 digit minute number, e.g. "04" or "59".
-- \<second>
-  - : 2 digit second number, e.g. "04" or "59".
+- `<day-name>`
+  - : One of `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, or `Sun` (case-sensitive).
+- `<day>`
+  - : 2 digit day number, e.g., "04" or "23".
+- `<month>`
+  - : One of `Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec` (case sensitive).
+- `<year>`
+  - : 4 digit year number, e.g., "1990" or "2016".
+- `<hour>`
+  - : 2 digit hour number, e.g., "09" or "23".
+- `<minute>`
+  - : 2 digit minute number, e.g., "04" or "59".
+- `<second>`
+  - : 2 digit second number, e.g., "04" or "59".
 - GMT
-  - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local
-    time.
+  - : Greenwich Mean Time. HTTP dates are always expressed in GMT, never in local time.
 
 ## Examples
 
+### Response with a Date header
+
+The following HTTP message is a successful `200` status, with a `Date` header showing the time the message originated.
+Other headers are omitted for brevity:
+
 ```http
-Date: Wed, 21 Oct 2015 07:28:00 GMT
+HTTP/1.1 200
+Content-Type: text/html
+Date: Tue, 29 Oct 2024 16:56:32 GMT
+
+<html lang="en-US" …
+```
+
+### Attempting to set the field value in JavaScript
+
+The `Date` header is a {{Glossary("forbidden header name")}}, so this code cannot set the message `Date` field:
+
+```js example-bad
+fetch("https://httpbin.org/get", {
+  headers: {
+    Date: new Date().toUTCString(),
+  },
+});
 ```
 
 ## Specifications

files/en-us/web/http/headers/device-memory/index.md

@@ -7,7 +7,12 @@ browser-compat: http.headers.Device-Memory
 
 {{HTTPSidebar}}{{securecontext_header}}
 
-The **`Device-Memory`** [device client hint](/en-US/docs/Web/HTTP/Client_hints#device_client_hints) request header field indicates the approximate amount of available RAM on the client device. The header is part of the {{DOMxRef("Device Memory API", "Device Memory API", "", "nocode")}}.
+The HTTP **`Device-Memory`** {{Glossary("request header")}} is used in [device client hints](/en-US/docs/Web/HTTP/Client_hints#device_client_hints) to indicate the approximate amount of available RAM on the client device, in gigabytes.
+The header is part of the {{DOMxRef("Device Memory API", "Device Memory API", "", "nocode")}}.
+
+Client hints are accessible only on secure origins.
+A server has to opt in to receive the `Device-Memory` header from the client, by first sending the {{HTTPHeader("Accept-CH")}} response header.
+Servers that opt in to the `Device-Memory` client hint will typically also specify it in the {{HTTPHeader("Vary")}} header to inform caches that the server may send different responses based on the header value in a request.
 
 <table class="properties">
   <tbody>
@@ -20,17 +25,11 @@ The **`Device-Memory`** [device client hint](/en-US/docs/Web/HTTP/Client_hints#d
     </tr>
     <tr>
       <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>no</td>
+      <td>No</td>
     </tr>
   </tbody>
 </table>
 
-> [!NOTE]
->
-> - Client Hints are accessible only on secure origins (via TLS).
-> - A server has to opt in to receive the `Device-Memory` header from the client, by sending the {{HTTPHeader("Accept-CH")}} response header.
-> - Servers that opt in to the `Device-Memory` client hint will typically also specify it in the {{HTTPHeader("Vary")}} header. This informs caches that the server may send different responses based on the header value in a request.
-
 ## Syntax
 
 ```http
@@ -41,12 +40,11 @@ Device-Memory: <number>
 
 - `<number>`
   - : The approximate amount of device RAM. Possible values are: `0.25`, `0.5`, `1`, `2`, `4`, `8`.
-
-The amount of device RAM can be used as a {{glossary("fingerprinting")}} variable, so values for the header are intentionally coarse to reduce the potential for its misuse.
+    The amount of device RAM can be used as a {{glossary("fingerprinting")}} variable, so values for the header are intentionally coarse to reduce the potential for its misuse.
 
 ## Examples
 
-The server first needs to opt in to receive `Device-Memory` header by sending the response headers {{HTTPHeader("Accept-CH")}} containing `Device-Memory`.
+The server first needs to opt in to receive `Device-Memory` header by sending the {{HTTPHeader("Accept-CH")}} response header containing `Device-Memory`:
 
 ```http
 Accept-CH: Device-Memory
@@ -73,11 +71,9 @@ Device-Memory: 1
 - {{DOMxRef("Navigator.deviceMemory")}}
 - {{DOMxRef("WorkerNavigator.deviceMemory")}}
 - Device client hints
-
   - {{HTTPHeader("Content-DPR")}}
   - {{HTTPHeader("DPR")}}
   - {{HTTPHeader("Viewport-Width")}}
   - {{HTTPHeader("Width")}}
-
 - {{HTTPHeader("Accept-CH")}}
-- [HTTP Caching > Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}}
+- [HTTP Caching: Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}}

files/en-us/web/http/headers/digest/index.md

@@ -15,10 +15,11 @@ browser-compat: http.headers.Digest
 > Use {{HTTPHeader("Content-Digest")}} instead.
 > For `id-*` digest algorithms, use {{HTTPHeader("Repr-Digest")}}.
 
-The **`Digest`** response or request HTTP header provides the other side with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_. It can be requested by using the {{HTTPHeader("Want-Digest")}} header.
+The HTTP **`Digest`** {{Glossary("request header")}} and {{Glossary("response header")}} provides the recipient with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_.
+It can be requested by using the {{HTTPHeader("Want-Digest")}} header.
 
 Representations are different forms of a particular resource that might be returned from a request: for example, the same resource might be formatted in a particular media type such as XML or JSON, localized to a particular written language or geographical region, and/or compressed or otherwise encoded for transmission.
-The _selected representation_ is the actual format of a resource that is returned following [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation), and can be determined from the response's {{Glossary("Representation header","Representation headers")}}.
+The _selected representation_ is a resource returned following [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation), and can be determined from the response's {{Glossary("Representation header","Representation headers")}}.
 
 The digest applies to the whole representation of a resource, not to a particular message.
 It can be used to verify that the representation data has not been modified during transmission.
@@ -30,11 +31,11 @@ It can be used to verify that the representation data has not been modified duri
   <tbody>
     <tr>
       <th scope="row">Header type</th>
-      <td>{{Glossary("Response header")}}</td>
+      <td>{{Glossary("Response header")}}, {{Glossary("Request header")}}</td>
     </tr>
     <tr>
       <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>no</td>
+      <td>No</td>
     </tr>
   </tbody>
 </table>
@@ -76,6 +77,5 @@ Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=,id-sha-256=0KJL0PvN
 ## See also
 
 - {{HTTPHeader("Want-Digest")}}
-
 - [HTTP range requests](/en-US/docs/Web/HTTP/Range_requests)
-- [`206 Partial Content`](/en-US/docs/Web/HTTP/Status/206)
+- {{HTTPStatus("206", "206 Partial Content")}}

files/en-us/web/http/headers/dnt/index.md

@@ -13,9 +13,8 @@ browser-compat: http.headers.DNT
 > [!NOTE]
 > The DNT (Do Not Track) specification has been discontinued. See {{domxref("Navigator.doNotTrack")}} for more information.
 
-The **`DNT`** (**D**o **N**ot
-**T**rack) request header indicates the user's tracking preference. It lets
-users indicate whether they would prefer privacy rather than personalized content.
+The HTTP **`DNT`** (Do Not Track) {{Glossary("request header")}} indicates the user's tracking preference.
+It lets users indicate whether they would prefer privacy rather than personalized content.
 
 DNT is deprecated in favor of [Global Privacy Control](https://globalprivacycontrol.org/), which is communicated to servers using the {{HTTPHeader("Sec-GPC")}} header, and accessible to clients from {{domxref("navigator.globalPrivacyControl")}}.
 
@@ -27,7 +26,7 @@ DNT is deprecated in favor of [Global Privacy Control](https://globalprivacycont
     </tr>
     <tr>
       <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>yes</td>
+      <td>Yes</td>
     </tr>
   </tbody>
 </table>
@@ -42,11 +41,11 @@ DNT: null
 
 ## Directives
 
-- 0
+- `0`
   - : The user prefers to allow tracking on the target site.
-- 1
+- `1`
   - : The user prefers not to be tracked on the target site.
-- null
+- `null`
   - : The user has not specified a preference about tracking.
 
 ## Examples

files/en-us/web/http/headers/downlink/index.md

@@ -9,7 +9,14 @@ browser-compat: http.headers.Downlink
 
 {{HTTPSidebar}} {{SeeCompatTable}}
 
-The **`Downlink`** [Client hint](/en-US/docs/Web/HTTP/Client_hints) request header field provides the approximate bandwidth of the client's connection to the server, in Mbps.
+The HTTP **`Downlink`** {{Glossary("request header")}} is used in [Client Hints](/en-US/docs/Web/HTTP/Client_hints) to provide the approximate bandwidth in Mbps of the client's connection to the server.
+
+The hint allows a server to choose what information is sent based on the network bandwidth.
+For example, a server might choose to send smaller versions of images and other resources on low bandwidth networks.
+
+> [!NOTE]
+> The {{HTTPHeader("Vary")}} header is used in responses to indicate that a different resource is sent for every different value of the header (see [HTTP Caching Vary](/en-US/docs/Web/HTTP/Caching#vary)).
+> Even if `Downlink` is used to configure what resources are sent, consider omitting it in the {{HTTPHeader("Vary")}} header — it is likely to change often, which effectively makes the resource uncacheable.
 
 <table class="properties">
   <tbody>
@@ -22,18 +29,11 @@ The **`Downlink`** [Client hint](/en-US/docs/Web/HTTP/Client_hints) request head
     </tr>
     <tr>
       <th scope="row">{{Glossary("Forbidden header name")}}</th>
-      <td>no</td>
+      <td>No</td>
     </tr>
   </tbody>
 </table>
 
-The `Downlink` value is given in Mbps and rounded to the nearest 25 kilobits per second to prevent [fingerprinting](/en-US/docs/Glossary/Fingerprinting). There are many other mechanisms an attacker might use to obtain similar information.
-
-The hint allows a server to choose what information is sent based on the network bandwidth. For example, a server might choose to send smaller versions of images and other resources on low bandwidth networks.
-
-> [!NOTE]
-> The {{HTTPHeader("Vary")}} header is used in responses to indicate that a different resource is sent for every different value of the header (see [HTTP Caching Vary](/en-US/docs/Web/HTTP/Caching#vary)). Even if `Downlink` is used to configure what resources are sent, consider omitting it in the {{HTTPHeader("Vary")}} header — it is likely to change often, which effectively makes the resource uncacheable.
-
 ## Syntax
 
 ```http
@@ -42,8 +42,9 @@ Downlink: <number>
 
 ## Directives
 
-- \<number>
+- `<number>`
   - : The downlink rate in Mbps, rounded to the nearest 25 kilobits.
+    The downlink rate may be used as a {{glossary("fingerprinting")}} variable, so values for the header are intentionally coarse to reduce the potential for its misuse.
 
 ## Examples
 
@@ -71,11 +72,9 @@ Downlink: 1.7
 
 - [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) (developer.chrome.com)
 - Network client hints
-
   - {{HTTPHeader("RTT")}}
   - {{HTTPHeader("ECT")}}
   - {{HTTPHeader("Save-Data")}}
-
 - {{HTTPHeader("Accept-CH")}}
-- [HTTP Caching > Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}}
+- [HTTP Caching: Vary](/en-US/docs/Web/HTTP/Caching#vary) and {{HTTPHeader("Vary")}}
 - {{domxref("NetworkInformation.effectiveType")}}