diff --git a/doc/cookie_deprecation.md b/doc/cookie_deprecation.md
new file mode 100644
index 0000000..65cb430
--- /dev/null
+++ b/doc/cookie_deprecation.md
@@ -0,0 +1,33 @@
+# Deprecation of cookie option
+
+## What?
+
+As of 0.8.8 the `cookie` option is deprecated and it will be removed.
+A new `auth` option was added.
+If you don't use the `cookie` otpion, you're not affected and don't need to read this.
+Note that this is different from `cookie_file`.
+
+## Why?
+
+The option was confusing:
+
+* If you entered the path to cookie file (usually `~/.bitcoin/.cookie`), it wouldn't work.
+* If you copied the contents of cookie file into it, `electrs` would break at the next restart of the system.
+* If you used a script to fix the above run before `electrs` starts, it'd still break if `bitcoind` restarted for any reason.
+* If you used `BindsTo` option of systemd, you'd solve the issue but introduce needless downtime and waste of performance.
+* Entering `username:password` was the only valid use of `cookie` but it had nothing to do with cookie.
+
+## What to do?
+
+If you're installing `electrs` for the first time, just don't use `cookie`.
+If you're updating, reconsider the motivation above.
+If you used copying script, just use `cookie_file` to get the cookie directly.
+If you also used `BindsTo`, we recommend removing it.
+If you used fixed username and password because you didn't know about cookie or did it before `cookie_file` was implemented, reconsider using cookie authentication.
+If you really have to use fixed username and password, specify them using `auth` option (`username:password` like before) and remove the `cookie` option.
+
+## When the option will be removed?
+
+Probably in a few months.
+It'll still be detected and turned into explicit error for a while to make sure people really see the message and know what's going on.
+You can see [the tracking issue #371](https://github.com/romanz/electrs/issues/371) to monitor the progress of the change.
diff --git a/doc/usage.md b/doc/usage.md
index 02b8097..81c7669 100644
--- a/doc/usage.md
+++ b/doc/usage.md
@@ -219,8 +219,6 @@ You need to use a number in config file if you want to increase verbosity (e.g.
 
 **Authentication**
 
-**Warning:** If you're reading this before version 0.8.8 exists either use `cookie_file` or check the version of documentation before this line was committed.
-
 In addition, config files support `auth` option to specify username and password.
 This is not available using command line or environment variables for security reasons (other applications could read it otherwise).
 **Important note**: `auth` is different from `cookie_file`, which points to a file containing the cookie instead of being the cookie itself!
@@ -449,6 +447,7 @@ $ ./contrib/addr.py 144STc7gcb9XCp6t4hvrcUEKg9KemivsCR  # sample address from bl
 > It's strongly recommended to use proper cookie authentication using `cookie_file`.
 > If you really have to use fixed username and password, explicitly specified in `bitcoind` config, use `auth` option instead.
 > Users of `btc-rpc-proxy` using `public:public` need to use `auth` too.
+> You can read [a detailed explanation of cookie deprecation with motivation explained](cookie_deprecation.md).
 
 As with any other application, you need to remember how you installed `electrs` to upgrade it.
 If you don't then here's a little help: run `which electrs` and compare the output