diff --git a/doc/build.md b/doc/build.md
new file mode 100644
index 0000000..3bc0a35
--- /dev/null
+++ b/doc/build.md
@@ -0,0 +1,17 @@
+Install `Go >= 1.14` and `gcc`. Get the source code:
+
+    git clone https://github.com/nkanaev/yarr.git
+    git clone https://github.com/nkanaev/gofeed.git yarr/gofeed
+
+Then run one of the corresponding commands:
+
+    # create a binary for the host os
+    make build_macos    # -> _output/macos/yarr.app
+    make build_linux    # -> _output/linux/yarr
+    make build_windows  # -> _output/windows/yarr.exe
+
+    # ... or start a dev server locally
+    go run main.go      # starts a server at http://localhost:7070
+
+    # ... or build a docker image
+    docker build -t yarr .
diff --git a/doc/changelog.txt b/doc/changelog.md
similarity index 100%
rename from doc/changelog.txt
rename to doc/changelog.md
diff --git a/doc/hacking.md b/doc/hacking.md
deleted file mode 100644
index eb282af..0000000
--- a/doc/hacking.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# hacking
-
-## build
-
-Install `Go >= 1.14` and `gcc`. Get the source code:
-
-```sh
-git clone https://github.com/nkanaev/yarr.git
-git clone https://github.com/nkanaev/gofeed.git
-mv gofeed yarr
-cd yarr
-```
-
-Then:
-
-```sh
-# create a binary for the host os
-make build_macos    # -> _output/macos/yarr.app
-make build_linux    # -> _output/linux/yarr
-make build_windows  # -> _output/windows/yarr.exe
-
-# ... or run locally (for testing & hacking)
-go run main.go      # starts a server at http://localhost:7070
-```
-
-## code of conduct
-
-Be excellent to each other. Party on, dudes!
diff --git a/doc/install.md b/doc/install.md
index 79e5e89..2ee2952 100644
--- a/doc/install.md
+++ b/doc/install.md
@@ -1,15 +1,22 @@
-# Linux desktop
+The latest binary releases for MacOS/Windows/Linux are available
+[here](https://github.com/nkanaev/yarr/releases/latest).
 
-Grab the latest linux binary, then run:
+## install (linux)
 
-```
-$ sudo mv /path/to/yarr /usr/local/bin
-$ sudo tee /usr/local/share/applications/yarr.desktop >/dev/null <<EOF
-[Desktop Entry]
-Name=yarr
-Exec=yarr -open
-Icon=rss
-Type=Application
-Categories=Internet;
-EOF
-```
+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/doc/platform.md b/doc/technotes.md
similarity index 100%
rename from doc/platform.md
rename to doc/technotes.md
diff --git a/artwork/promo.png b/etc/promo.png
similarity index 100%
rename from artwork/promo.png
rename to etc/promo.png
diff --git a/artwork/promo.xml b/etc/promo.xml
similarity index 100%
rename from artwork/promo.xml
rename to etc/promo.xml
diff --git a/readme.md b/readme.md
index 44af7ef..bfdee0d 100644
--- a/readme.md
+++ b/readme.md
@@ -1,15 +1,11 @@
 # yarr
 
-yet another rss reader.
+**yarr** (yet another rss reader) is a web-based feed aggregator which can be used both
+as a desktop application and a self-hosted server.
 
-![screenshot](https://github.com/nkanaev/yarr/blob/master/artwork/promo.png?raw=true)
+It is written in Go with the frontend in Vue.js. The storage is backed by SQLite.
 
-*yarr* is a server written in Go with the frontend in Vue.js. The storage is backed by SQLite.
-
-The goal of the project is to provide a desktop application accessible via web browser.
-Longer-term plans include a self-hosted solution for individuals.
-
-[download](https://github.com/nkanaev/yarr/releases/latest)
+![screenshot](etc/promo.png)
 
 ## credits