diff --git a/README.md b/README.md
index 1d0d27fe..d4e0db00 100644
--- a/README.md
+++ b/README.md
@@ -10,95 +10,14 @@ works in the background.
See [omnisharp-emacs Features](doc/features.md).
-## Installation of the omnisharp-roslyn server application
-This emacs package requires the [omnisharp-roslyn][] server program.
-
-You have three options here:
- * You can use M-x `omnisharp-install-server` to install omnisharp-server binary automatically.
-
- * *NOTE: On Windows, this command requires PowerShell v5+ to be installed
- – see [omnisharp-emacs#275](https://github.com/OmniSharp/omnisharp-emacs/issues/275).*
-
- * *NOTE 2*: On macOS and Linux omnisharp server binary requires
- [mono](http://www.mono-project.com/) to be installed on your system.
-
- * Download and extract server binaries
- manually and then point `omnisharp-server-executable-path` variable to the binary.
-
- * Build the server yourself from the source.
- Building instructions are detailed in
- [omnisharp-roslyn building page](https://github.com/OmniSharp/omnisharp-roslyn#building).
-
-### Manual installation on macOS with brew
-
-brew install omnisharp/omnisharp-roslyn/omnisharp-mono
-
-
-Then you need to set the `omnisharp-server-executable-path`:
-
-```lisp
-(setq omnisharp-server-executable-path "/usr/local/bin/omnisharp")
-```
-
-### Manual installation on Linux
-Extract binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases).
-
-Then you need to set the `omnisharp-server-executable-path`:
-
-```lisp
-(setq omnisharp-server-executable-path "")
-```
-
-### Manual installation on Windows (non-Cygwin)
-Use binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases).
-
-*NOTE: For the moment you HAVE to use the `omnisharp-win-x86-net46.zip` bundle as -x64- one makes emacs
-to crash in `src/w32proc.c:w32_executable_type`.* See https://github.com/OmniSharp/omnisharp-emacs/issues/315
-
-Then you need to set the `omnisharp-server-executable-path` the path
-to where you have extracted server file, e.g.:
-
-```lisp
-(setq omnisharp-server-executable-path "C:\\Bin\\omnisharp-roslyn\\OmniSharp.exe")
-```
-
-### Manual installation on windows (with Cygwin)
-Use binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases):
-
- - https://github.com/OmniSharp/omnisharp-roslyn/releases/download/v1.9-beta22/omnisharp-win-x64-net46.zip
-
-If I use omnisharp-roslyn net46 directly, omnisharp-emacs hangs when interacting via stdio.
-This seems to be a difference in how console IO is handled in newer versions of .Net.
-My workaround involves using a wrapper written in C#:
-
-https://gist.github.com/corngood/d982c3c21c016127a2f1600dc895c000
-
-You need to compile the wrapper against an older .net framework (3.5 seems to work). A simple way to use the wrapper is to create a shell script like:
-
-```shell
-#!/bin/sh
-set -e
-[path-to-wrapper-exe] "$(cygpath -w [path-to-omnisharp-exe])" "$@"
-```
-
-If you name this script OmniSharp, and put it in your path (e.g. /usr/local/bin/OmniSharp),
-`omnisharp-emacs` should find it and launch omnisharp correctly.
-Or you can point to it directly in your init.el
-
-```lisp
-(setq omnisharp-server-executable-path "/home//bin/OmniSharp")
-```
-
-## Package Installation and Configuration
+## Package Installation
This package requires Emacs 24.3 and above. It has been tested on
Ubuntu, Windows 7+ and on macOS.
### Installation on Spacemacs
Add `csharp` layer to `dotspacemacs-configuration-layers` on
your `.spacemacs` file. `csharp-mode` and `omnisharp` packages
-will get installed automatically on restart for you.
-
- * TODO: as of 2017-02-19 `csharp` layer installs non-roslyn version of omnisharp-emacs.
+will get installed automatically for you on restart.
### Installation on Regular Emacs
To install, use [MELPA][].
@@ -120,16 +39,34 @@ something like this to `csharp-mode-hook` on your `init.el`:
(add-hook 'csharp-mode-hook 'omnisharp-mode)
```
-## Configuration and commands available
-To start it, use `M-x omnisharp-start-omnisharp-server RET`.
-The command will ask you for a solution file or a directory
-you want to code in.
+For autocompletion via company mode you will also need this in your `init.el`:
+
+```
+(eval-after-load
+ 'company
+ '(add-to-list 'company-backends 'company-omnisharp))
+```
+## Server Installation
+This emacs package requires the [omnisharp-roslyn][] server program.
Emacs will manage connection to the server as a subprocess.
+The easiest way to install the server is to invoke
+`M-x omnisharp-install-server` and follow instructions on minibufer.
+
+If that fails (or you feel adventurous) please see [installing omnisharp server](doc/server-installation.md)
+on how to install the server manually.
+
+## Configuration
+To start using omnisharp-emacs, start the server with `M-x omnisharp-start-omnisharp-server RET`.
+The command will ask you for a project or solution file you want to code in.
+
You will probably want to create a custom configuration for accessing
-omnisharp-emacs in your normal coding sessions. There is an example
-configuration for evil-mode included in the project.
+omnisharp-emacs in your normal coding sessions.
+Usually all this customization goes in your custom `csharp-mode-hook` in your `init.el`.
+
+There is also an example configuration for evil-mode included in the project,
+please see `doc/example-config-for-evil-mode.el`.
* * * * *
diff --git a/doc/server-installation.md b/doc/server-installation.md
new file mode 100644
index 00000000..7965374f
--- /dev/null
+++ b/doc/server-installation.md
@@ -0,0 +1,78 @@
+# Installation of the omnisharp-roslyn server application
+This emacs package requires the [omnisharp-roslyn](https://github.com/OmniSharp/omnisharp-roslyn) server program.
+
+You have three options here:
+ * You can use M-x `omnisharp-install-server` to install omnisharp-server binary automatically.
+
+ * *NOTE: On Windows, this command requires PowerShell v5+ to be installed
+ – see [omnisharp-emacs#275](https://github.com/OmniSharp/omnisharp-emacs/issues/275).*
+
+ * *NOTE 2*: On macOS and Linux omnisharp server binary requires
+ [mono](http://www.mono-project.com/) to be installed on your system.
+
+ * Download and extract server binaries
+ manually and then point `omnisharp-server-executable-path` variable to the binary.
+
+ * Build the server yourself from the source.
+ Building instructions are detailed in
+ [omnisharp-roslyn building page](https://github.com/OmniSharp/omnisharp-roslyn#building).
+
+## Manual installation on macOS with brew
+
+brew install omnisharp/omnisharp-roslyn/omnisharp-mono
+
+
+Then you need to set the `omnisharp-server-executable-path`:
+
+```lisp
+(setq omnisharp-server-executable-path "/usr/local/bin/omnisharp")
+```
+
+## Manual installation on Linux
+Extract binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases).
+
+Then you need to set the `omnisharp-server-executable-path`:
+
+```lisp
+(setq omnisharp-server-executable-path "")
+```
+
+## Manual installation on Windows (non-Cygwin)
+Use binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases).
+
+*NOTE: For the moment you HAVE to use the `omnisharp-win-x86-net46.zip` bundle as -x64- one makes emacs
+to crash in `src/w32proc.c:w32_executable_type`.* See https://github.com/OmniSharp/omnisharp-emacs/issues/315
+
+Then you need to set the `omnisharp-server-executable-path` the path
+to where you have extracted server file, e.g.:
+
+```lisp
+(setq omnisharp-server-executable-path "C:\\Bin\\omnisharp-roslyn\\OmniSharp.exe")
+```
+
+## Manual installation on windows (with Cygwin)
+Use binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases):
+
+ - https://github.com/OmniSharp/omnisharp-roslyn/releases/download/v1.9-beta22/omnisharp-win-x64-net46.zip
+
+If I use omnisharp-roslyn net46 directly, omnisharp-emacs hangs when interacting via stdio.
+This seems to be a difference in how console IO is handled in newer versions of .Net.
+My workaround involves using a wrapper written in C#:
+
+https://gist.github.com/corngood/d982c3c21c016127a2f1600dc895c000
+
+You need to compile the wrapper against an older .net framework (3.5 seems to work). A simple way to use the wrapper is to create a shell script like:
+
+```shell
+#!/bin/sh
+set -e
+[path-to-wrapper-exe] "$(cygpath -w [path-to-omnisharp-exe])" "$@"
+```
+
+If you name this script OmniSharp, and put it in your path (e.g. /usr/local/bin/OmniSharp),
+`omnisharp-emacs` should find it and launch omnisharp correctly.
+Or you can point to it directly in your init.el
+
+```lisp
+(setq omnisharp-server-executable-path "/home//bin/OmniSharp")
+```
diff --git a/omnisharp-server-actions.el b/omnisharp-server-actions.el
index 2042e6f2..04812bb0 100644
--- a/omnisharp-server-actions.el
+++ b/omnisharp-server-actions.el
@@ -20,7 +20,7 @@ to use server installed via `omnisharp-install-server`.
(progn
(message "omnisharp: No omnisharp server could be found.")
(message (concat "omnisharp: Please use M-x 'omnisharp-install-server' or download server manually"
- " as detailed in https://github.com/OmniSharp/omnisharp-emacs/blob/master/README.md#installation-of-the-omnisharp-roslyn-server-application"))
+ " as detailed in https://github.com/OmniSharp/omnisharp-emacs/blob/master/doc/server-installation.md"))
nil)))))
(defun omnisharp--do-server-start (path-to-project server-executable-path)
diff --git a/omnisharp-server-installation.el b/omnisharp-server-installation.el
index dd021029..15a137cb 100644
--- a/omnisharp-server-installation.el
+++ b/omnisharp-server-installation.el
@@ -107,7 +107,7 @@ See https://github.com/OmniSharp/omnisharp-emacs/issues/315"
(message (format "omnisharp: server was installed to \"%s\"; you can now do M-x 'omnisharp-start-omnisharp-server' "
executable-path))
(message (concat "omnisharp: server could not be installed automatically. "
- "Please check https://github.com/OmniSharp/omnisharp-emacs/blob/master/README.md#installation-of-the-omnisharp-roslyn-server-application for instructions."))))))
+ "Please check https://github.com/OmniSharp/omnisharp-emacs/blob/master/doc/server-installation.md for instructions."))))))
(message (format "omnisharp: server is already installed (%s)"
expected-executable-path)))))