diff --git a/files/en-us/web/api/document/write/index.md b/files/en-us/web/api/document/write/index.md
index 0503f014512ca78..5672a726eb3c987 100644
--- a/files/en-us/web/api/document/write/index.md
+++ b/files/en-us/web/api/document/write/index.md
@@ -1,5 +1,5 @@
 ---
-title: Document.write()
+title: document.write()
 slug: Web/API/Document/write
 page-type: web-api-instance-method
 tags:
@@ -13,7 +13,13 @@ browser-compat: api.Document.write
 ---
 {{ApiRef("DOM")}}
 
-The **`Document.write()`** method writes a string of text to a document stream opened by {{domxref("document.open()")}}.
+> **Warning:** Use of the `document.write()` method in strongly discouraged.
+>
+> As [the HTML spec itself warns](https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#document.write()):
+>> This method has very idiosyncratic behavior. In some cases, this method can affect the state of the [HTML parser](https://html.spec.whatwg.org/multipage/parsing.html#html-parser) while the parser is running, resulting in a DOM that does not correspond to the source of the document (e.g. if the string written is the string "`<plaintext>`" or "`<!--`"). In other cases, the call can clear the current page first, as if [`document.open()`](https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#dom-document-open) had been called. In yet more cases, the method is simply ignored, or throws an exception. Users agents are [explicitly allowed to avoid executing `script` elements inserted via this method](https://html.spec.whatwg.org/multipage/parsing.html#document-written-scripts-intervention). And to make matters even worse, the exact behavior of this method can in some cases be dependent on network latency, which can lead to failures that are very hard to debug. For all these reasons, use of this method is strongly discouraged.
+> Therefore, avoid using `document.write()` — and if possible, update any existing code that is still using it.
+
+The **`document.write()`** method writes a string of text to a document stream opened by {{domxref("document.open()")}}.
 
 > **Note:** Because `document.write()` writes to the document **stream**, calling `document.write()` on a closed (loaded) document automatically calls `document.open()`, [which will clear the document](/en-US/docs/Web/API/Document/open#notes).
 
@@ -72,7 +78,7 @@ If the `document.write()` call is embedded within an inline HTML `<script>` tag,
 </script>
 ```
 
-> **Note:** `document.write()` and {{domxref("document.writeln")}} [do not work in XHTML documents](/en-US/docs/Archive/Web/Writing_JavaScript_for_HTML) (you'll get an "Operation is not supported" \[`NS_ERROR_DOM_NOT_SUPPORTED_ERR`] error in the error console). This happens when opening a local file with the .xhtml file extension or for any document served with an `application/xhtml+xml` {{Glossary("MIME type")}}. More information is available in the [W3C XHTML FAQ](https://www.w3.org/MarkUp/2004/xhtml-faq#docwrite).
+> **Note:** `document.write()` and {{domxref("document.writeln")}} do not work in XHTML documents (you'll get an "Operation is not supported" \[`NS_ERROR_DOM_NOT_SUPPORTED_ERR`] error in the error console). This happens when opening a local file with the .xhtml file extension or for any document served with an `application/xhtml+xml` {{Glossary("MIME type")}}. More information is available in the [W3C XHTML FAQ](https://www.w3.org/MarkUp/2004/xhtml-faq#docwrite).
 
 > **Note:** Using `document.write()` in [deferred](/en-US/docs/Web/HTML/Element/script#attr-defer) or [asynchronous](/en-US/docs/Web/HTML/Element/script#attr-async) scripts will be ignored and you'll get a message like "A call to `document.write()` from an asynchronously-loaded external script was ignored" in the error console.