diff --git a/llvm/docs/UserGuides.rst b/llvm/docs/UserGuides.rst
index 9ae0d36011154..6fb61f2d3a252 100644
--- a/llvm/docs/UserGuides.rst
+++ b/llvm/docs/UserGuides.rst
@@ -123,13 +123,14 @@ LLVM Builds and Distributions
 Optimizations
 -------------
 
-:doc:`WritingAnLLVMPass`
-   Information on how to write LLVM transformations and analyses.
-
 :doc:`WritingAnLLVMNewPMPass`
    Information on how to write LLVM transformations under the new pass
    manager.
 
+:doc:`WritingAnLLVMPass`
+   Information on how to write LLVM transformations and analyses under the
+   legacy pass manager.
+
 :doc:`Passes`
    A list of optimizations and analyses implemented in LLVM.
 
diff --git a/llvm/docs/WritingAnLLVMNewPMPass.rst b/llvm/docs/WritingAnLLVMNewPMPass.rst
index 799863c7864ec..ea30d637347f1 100644
--- a/llvm/docs/WritingAnLLVMNewPMPass.rst
+++ b/llvm/docs/WritingAnLLVMNewPMPass.rst
@@ -10,6 +10,11 @@ Writing an LLVM Pass
 Introduction --- What is a pass?
 ================================
 
+.. warning::
+  This document deals with the new pass manager. LLVM uses the legacy pass
+  manager for the codegen pipeline. For more details, see
+  :doc:`WritingAnLLVMPass` and :doc:`NewPassManager`.
+
 The LLVM pass framework is an important part of the LLVM system, because LLVM
 passes are where most of the interesting parts of the compiler exist. Passes
 perform the transformations and optimizations that make up the compiler, they
@@ -29,11 +34,6 @@ We start by showing you how to construct a pass, from setting up the build,
 creating the pass, to executing and testing it. Looking at existing passes is
 always a great way to learn details.
 
-.. warning::
-  This document deals with the new pass manager. LLVM uses the legacy pass
-  manager for the codegen pipeline. For more details, see
-  :doc:`WritingAnLLVMPass` and :doc:`NewPassManager`.
-
 Quick Start --- Writing hello world
 ===================================
 
diff --git a/llvm/docs/WritingAnLLVMPass.rst b/llvm/docs/WritingAnLLVMPass.rst
index b94669917c907..a3602e7fbc31f 100644
--- a/llvm/docs/WritingAnLLVMPass.rst
+++ b/llvm/docs/WritingAnLLVMPass.rst
@@ -1,6 +1,6 @@
-====================
-Writing an LLVM Pass
-====================
+========================================
+Writing an LLVM Pass (legacy PM version)
+========================================
 
 .. program:: opt
 
@@ -10,6 +10,13 @@ Writing an LLVM Pass
 Introduction --- What is a pass?
 ================================
 
+.. warning::
+  This document deals with the legacy pass manager. LLVM uses the new pass
+  manager for the optimization pipeline (the codegen pipeline
+  still uses the legacy pass manager), which has its own way of defining
+  passes. For more details, see :doc:`WritingAnLLVMNewPMPass` and
+  :doc:`NewPassManager`.
+
 The LLVM Pass Framework is an important part of the LLVM system, because LLVM
 passes are where most of the interesting parts of the compiler exist.  Passes
 perform the transformations and optimizations that make up the compiler, they
@@ -34,13 +41,6 @@ We start by showing you how to construct a pass, everything from setting up the
 code, to compiling, loading, and executing it.  After the basics are down, more
 advanced features are discussed.
 
-.. warning::
-  This document deals with the legacy pass manager. LLVM uses the new pass
-  manager for the optimization pipeline (the codegen pipeline
-  still uses the legacy pass manager), which has its own way of defining
-  passes. For more details, see :doc:`WritingAnLLVMNewPMPass` and
-  :doc:`NewPassManager`.
-
 Quick Start --- Writing hello world
 ===================================
 
@@ -224,6 +224,13 @@ can have them) to be useful.
 Running a pass with ``opt``
 ---------------------------
 
+.. warning::
+  This document deals with the legacy pass manager. The :program:`opt` tool no
+  longer supports running legacy passes (except for certain hardcoded backend
+  passes and when using bugpoint). So the examples below for loading and
+  running legacy passes using :program:`opt` are deprecated and no longer
+  guaranteed to work.
+
 Now that you have a brand new shiny shared object file, we can use the
 :program:`opt` command to run an LLVM program through your pass.  Because you
 registered your pass with ``RegisterPass``, you will be able to use the