diff --git a/doc/install.md b/doc/install.md
deleted file mode 100644
index 94645ec..0000000
--- a/doc/install.md
+++ /dev/null
@@ -1,19 +0,0 @@
-## install (linux)
-
-The Linux version doesn't come with the desktop environment integration.
-For easy access you can manually create a desktop menu entry by
-by following the steps below:
-
-    # get the latest linux binary zip
-    unzip -x yarr*.zip
-    sudo mv yarr /usr/local/bin/yarr
-    sudo nano /usr/local/share/applications/yarr.desktop
-
-and paste the content below:
-
-    [Desktop Entry]
-    Name=yarr
-    Exec=/usr/loca/bin -open
-    Icon=rss
-    Type=Application
-    Categories=Internet;
diff --git a/readme.md b/readme.md
index 6bab10c..9a6e76d 100644
--- a/readme.md
+++ b/readme.md
@@ -7,7 +7,47 @@ It is written in Go with the frontend in Vue.js. The storage is backed by SQLite
 
 ![screenshot](etc/promo.png)
 
-[download](https://github.com/nkanaev/yarr/releases/latest)
+## usage
+
+The latest prebuilt version for Linux/MacOS/Windows is available
+[here](https://github.com/nkanaev/yarr/releases/latest).
+
+### macos
+
+Download `yarr-*-macos64.zip`, unzip it, place `yarr.app` in `/Applications` folder.
+
+The binaries are not signed, because the author doesn't want to buy a certificate.
+Apple hates cheapskate developers, therefore the OS will refuse to run the application.
+To bypass these measures, you can run the command below:
+
+    xattr -d com.apple.quarantine /Applications/yarr.app
+
+### windows
+
+Download `yarr-*-windows32.zip`, unzip it, place wherever you'd like to
+(`C:\Program Files` or Recycle Bin). Create a shortcut manually if you'd like to.
+
+Microsoft doesn't like cheapskate developers too,
+but might only gently warn you about that, which you can safely ignore.
+
+### linux
+
+The Linux version doesn't come with the desktop environment integration.
+For easy access you can manually create a desktop menu entry by
+by following the steps below:
+
+    unzip -x yarr*.zip
+    sudo mv yarr /usr/local/bin/yarr
+    sudo nano /usr/local/share/applications/yarr.desktop
+
+and paste the content below:
+
+    [Desktop Entry]
+    Name=yarr
+    Exec=/usr/loca/bin -open
+    Icon=rss
+    Type=Application
+    Categories=Internet;
 
 ## build