diff --git a/NEWS.md b/NEWS.md
index 135cba59..16e67fd3 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -2,6 +2,7 @@
 
 ## 2.8.0 / ???
 
+* Project middleware, hooks, and the `:test` profile are considered deprecated. (Phil Hagelberg)
 * JVMs on 8u131 and newer will default to using cgroups settings for memory limits. (Phil Hagelberg)
 * Add `:query` subcommand to `deps` to quickly find latest versions. (Phil Hagelberg)
 * Fix a bug where dependency resolution wasn't cached correctly. (Phil Hagelberg)
diff --git a/doc/PLUGINS.md b/doc/PLUGINS.md
index a20b2ebb..ad97e62b 100644
--- a/doc/PLUGINS.md
+++ b/doc/PLUGINS.md
@@ -30,7 +30,7 @@
 
 # Leiningen Plugins
 
-Leiningen tasks are simply functions named $TASK in a leiningen.$TASK
+Leiningen tasks are simply functions named `$TASK` in a `leiningen.$TASK`
 namespace. So writing a Leiningen plugin is just a matter of creating
 a project that contains such a function, but much of this
 documentation applies equally to the tasks that ship with Leiningen
@@ -121,11 +121,11 @@ still passed in as strings; it's up to your function to call `read-string`
 on the arguments if you want keywords, symbols, integers, etc. Keep
 this in mind when calling other tasks as functions too.
 
-Most tasks may only be run in the context of another project. If your
+Most tasks may only be run in the context of a project. If your
 task can be run outside a project directory, add `^:no-project-needed`
 as metadata to your task defn to indicate so. Your task must still
 accept a project as its first argument, but it will be allowed to be
-nil. Leiningen will still pass you the project as first argument, if
+nil. Leiningen will still pass you the project as first argument if
 lein is called from within a project. If called outside of a project,
 lein will send in profile information from `$HOME/.lein/profiles.clj`
 and similar sources as a map similar to a project map. Other tools using
@@ -282,6 +282,11 @@ downstream artifacts, like `jar`, `uberjar`, and `pom`.
 
 ### Hooks
 
+**Note**: Leiningen supports loading hooks from plugins; however this
+mechanism is extremely error-prone and difficult to debug. It should
+be considered deprecated as of 2.8.0 onward and will continue to work
+until version 3.0 but is strongly advised against.
+
 You can modify the behaviour of built-in Leiningen tasks to a degree
 using hooks. Hook functionality is provided by the
 [Robert Hooke](https://github.com/technomancy/robert-hooke) library,
@@ -335,6 +340,11 @@ before manually specified hooks.
 
 ### Project Middleware
 
+**Note**: Leiningen supports project middleware in plugins;
+however this mechanism is extremely error-prone and difficult to
+debug. It should be considered deprecated as of 2.8.0 onward and will
+continue to work until version 3.0 but is strongly advised against.
+
 Project middleware is just a function that is called on a project map
 returning a new project map. Middleware gives a plugin the power to do
 any kind of transformation on the project map. However, problems with
@@ -429,7 +439,7 @@ middleware.
 
 ## Clojure Version
 
-Leiningen 2.5.2 and on uses Clojure 1.7.0. If you need to use a
+Leiningen 2.7.0 and on uses Clojure 1.8.0. If you need to use a
 different version of Clojure from within a Leiningen plugin, you can
 use `eval-in-project` with a dummy project argument:
 
diff --git a/doc/PROFILES.md b/doc/PROFILES.md
index 8e165393..2be2b17f 100644
--- a/doc/PROFILES.md
+++ b/doc/PROFILES.md
@@ -121,7 +121,9 @@ default when running lein tasks.  If not overridden, this is set to
 
 Some tasks automatically merge a profile if specified.  Examples of
 these are the `:test` profile, when running the `test` task, and the
-`:repl` profile, when running the `repl` task.
+`:repl` profile, when running the `repl` task. Please note that
+putting things in the `:test` profile is strongly advised against as
+it can result in tests which can't be run from the repl.
 
 ### Replacing Default Repl Dependencies