diff --git a/README.md b/README.md
index 1d91535d89..7d03349b8d 100644
--- a/README.md
+++ b/README.md
@@ -38,20 +38,6 @@ git clone https://github.com/PowerShell/PowerShell.git
 cd PowerShell
 ```
 
-#### Linux
-
-Linux will need every submodule, so update them recursively:
-
-```sh
-git submodule update --init --recursive
-```
-
-The `src/omi` submodule requires your GitHub user to have joined the Microsoft
-organization. If it fails to check out, Git will bail and not check out further
-submodules either. Please follow the instructions on the [Open Source Hub][].
-
-[Open Source Hub]: https://opensourcehub.microsoft.com/articles/how-to-join-microsoft-github-org-self-service
-
 #### Windows
 
 On Windows, many fewer submodules are needed, so specify them:
@@ -62,56 +48,6 @@ git submodule update --init --recursive -- src/windows-build src/Microsoft.Power
 
 ## Setup build environment
 
-We use the [.NET Command Line Interface][dotnet-cli] (`dotnet`) to
-build the managed components, and [CMake][] to build the native
-components (on non-Windows platforms). Install `dotnet` by following
-their [documentation][cli-docs].
-
-The version of .NET CLI is very important, you want a recent 1.0.0 beta
-(**not** 1.0.1). The following instructions will install precisely
-1.0.0.001888, though any 1.0.0 version *should* work.
-
-> Previous installations of DNX, `dnvm`, or older installations of .NET CLI
-> can cause odd failures when running. Please check your version.
-
-[dotnet-cli]: https://github.com/dotnet/cli#new-to-net-cli
-[cli-docs]: https://dotnet.github.io/getting-started/
-[CMake]: https://cmake.org/cmake/help/v2.8.12/cmake.html
-
-### Linux
-
-Tested on Ubuntu 14.04.
-
-This installs the .NET CLI package feed. The benefit to this is that
-installing `dotnet` using `apt-get` will also install all of its
-dependencies automatically.
-
-```sh
-sudo sh -c 'echo "deb [arch=amd64] http://apt-mo.trafficmanager.net/repos/dotnet/ trusty main" > /etc/apt/sources.list.d/dotnetdev.list'
-sudo apt-key adv --keyserver apt-mo.trafficmanager.net --recv-keys 417A0893
-sudo apt-get update
-sudo apt-get install dotnet=1.0.0.001675-1
-```
-
-The drawback of using the feed is that it gets out of date. The pinned
-version is the most recent package published to the feed, but newer
-packages are available. To upgrade the package, install it by
-hand. Unfortunately, `dpkg` does not handle dependency resolution, so
-it is recommended to first install the older version from the feed,
-and then upgrade it.
-
-```sh
-wget https://dotnetcli.blob.core.windows.net/dotnet/beta/Installers/Latest/dotnet-ubuntu-x64.latest.deb
-sudo dpkg -i ./dotnet-ubuntu-x64.latest.deb
-```
-
-Additionally, PowerShell on Linux builds a native library, so install
-the following additional build / debug tools.
-
-```sh
-sudo apt-get install g++ cmake make lldb-3.6 strace
-```
-
 ### Windows
 
 Tested on Windows 10 and Windows Server 2012 R2.
@@ -141,23 +77,11 @@ test on OS X, but some developers use PowerShell on 10.10 and 10.11.
 **The command `dotnet restore` must be done at least once from the top directory
 to obtain all the necessary .NET packages.**
 
-Build with `./build.sh` on Linux and OS X.
-
 `Start-PSBuild` from module `./PowerShellGitHubDev.psm1` on Windows
 and Linux / OS X, if you are self-hosting PowerShell.
 
 Specifically:
 
-### Linux
-
-In Bash:
-
-```sh
-cd PowerShell
-dotnet restore
-./build.sh
-```
-
 ### Windows
 
 In PowerShell:
@@ -180,11 +104,6 @@ otherwise open a new issue on GitHub.
 
 The local managed host has built-in documentation via `--help`.
 
-### Linux / OS X
-
-- launch local shell with `./bin/powershell`
-- run tests with `./pester.sh`
-
 ### Windows
 
 - launch `./bin/powershell.exe`
@@ -278,39 +197,6 @@ ip -f inet addr show dev eth0
 
 The variable `$BIN` is the output directory, `bin`.
 
-### Managed
-
-Builds with `dotnet`. Publishes all dependencies into the `bin` directory.
-Emits its own native host as `bin/powershell`. Uses a `Linux` configuration to
-add a preprocessor definition. The `CORECLR` definition is added only when
-targeting the `netstandard1.5` framework. The `LINUX` definition is added only
-when `--configuration Linux` is used.
-
-```sh
-cd src/Microsoft.PowerShell.Linux.Host
-dotnet publish --configuration Linux
-```
-
-### Native
-
-The `libpsl-native.so` library consists of native functions that
-`CorePsPlatform.cs` P/Invokes.
-
-#### libpsl-native
-
-Driven by CMake, with its own unit tests using Google Test.
-
-```sh
-cd src/libpsl-native
-cmake -DCMAKE_BUILD_TYPE=Debug .
-make -j
-ctest -V
-# Deploy development copy of libpsl-native
-cp native/libpsl-native.* $BIN
-```
-
-The output is a `.so` on Linux and `.dylib` on OS X. It is unnecessary for Windows.
-
 ### PSRP
 
 #### OMI
diff --git a/docs/building/linux.md b/docs/building/linux.md
new file mode 100644
index 0000000000..2027a20fbc
--- /dev/null
+++ b/docs/building/linux.md
@@ -0,0 +1,166 @@
+Build PowerShell on Linux
+=========================
+
+This guide will walk you through building PowerShell on Linux. We'll
+start by showing how to set up your environment from scratch.
+
+Environment
+===========
+
+These instructions are written assuming the Ubuntu 14.04 LTS, since
+that's the distro the team uses.
+
+Toolchain Setup
+---------------
+
+We use the [.NET Command Line Interface][dotnet-cli] (`dotnet`) to
+build the managed components, and [CMake][] to build the native
+components. Install the following packages for the toolchain:
+
+- `dotnet`
+- `cmake`
+- `make`
+- `g++`
+- `libunwind8`
+- `libicu52`
+
+And for debgging:
+
+- `strace`
+- `lldb-3.6`
+
+In order to get `dotnet`, we need to add an additional package source:
+
+```sh
+sudo sh -c 'echo "deb [arch=amd64] http://apt-mo.trafficmanager.net/repos/dotnet/ trusty main" > /etc/apt/sources.list.d/dotnetdev.list'
+sudo apt-key adv --keyserver apt-mo.trafficmanager.net --recv-keys 417A0893
+sudo apt-get update
+```
+
+Then install the packages you need:
+
+```sh
+sudo apt-get install dotnet cmake make g++ libunwind8 libicu52 strace lldb-3.6
+```
+
+[dotnet-cli]: https://github.com/dotnet/cli#new-to-net-cli
+[CMake]: https://cmake.org/cmake/help/v2.8.12/cmake.html
+
+.NET CLI
+--------
+
+If you have any problems installing `dotnet`, please see their
+[documentation][cli-docs].
+
+The version of .NET CLI is very important, you want a recent build of
+1.0.0 (**not** 1.0.1).
+
+Previous installations of DNX, `dnvm`, or older installations of .NET
+CLI can cause odd failures when running. Please check your version.
+
+The drawback of using the feed is that it gets out of date. To upgrade
+the package, install it by hand. Unfortunately, `dpkg` does not handle
+dependency resolution, so it is recommended to first install the older
+version from the feed, and then upgrade it.
+
+```sh
+wget https://dotnetcli.blob.core.windows.net/dotnet/beta/Installers/Latest/dotnet-ubuntu-x64.latest.deb
+sudo dpkg -i ./dotnet-ubuntu-x64.latest.deb
+```
+
+[cli-docs]: https://dotnet.github.io/getting-started/
+
+Git Setup
+---------
+
+Please clone the superproject (this repo) and initialize a subset of
+the submodules:
+
+```sh
+git clone https://github.com/PowerShell/PowerShell.git
+cd PowerShell
+git submodule update --init --recursive -- src/windows-build src/libpsl-native src/Microsoft.PowerShell.Linux.Host/Modules/Pester
+```
+
+Build using our module
+======================
+
+We maintain a `PowerShellGitHubDev.psm1` PowerShell module with the
+function `Start-PSBuild` to build PowerShell. Since this is PowerShell
+code, it requires self-hosting. Fortunately, this is as easy as
+downloading and installing the package. Unfortunately, while the
+repository is still private, the package cannot be downloaded as
+simply as with `wget`. We have a script that wraps the GitHub API and
+uses a personal access token to authorize and obtain the package.
+
+> You can alternativelly download via a browser and upload it to your
+> box via some other method
+
+```sh
+GITHUB_TOKEN=<replace with your token> ./download.sh
+sudo dpkg -i ./powershell.deb
+powershell
+```
+
+You should now be in a `powershell` console host that is installed
+separately from any development copy you're about to build. Just
+import our module and build!
+
+```powershell
+Import-Module ./PowerShellGitHubDev.psm1
+Start-PSBuild
+```
+
+Congratulations! If everything went right, PowerShell is now built and
+executable as `./bin/powershell`.
+
+> Note that the `./build.sh` script is deprecated and may be removed
+
+You can run our cross-platform Pester tests with `./bin/powershell -c
+"Invoke-Pester test/powershell"`.
+
+Build manually
+==============
+
+The following goes into detail about what `Start-PSBuild` does.
+
+Build the native library
+------------------------
+
+The `libpsl-native.so` library consists of native functions that
+`CorePsPlatform.cs` P/Invokes.
+
+```sh
+pushd src/libpsl-native
+cmake -DCMAKE_BUILD_TYPE=Debug .
+make -j
+make test
+popd
+```
+
+This library will be emitted in the
+`src/Microsoft.PowerShell.Linux.Host` project, where `dotnet` consumes
+it as "content" and thus automatically deploys it.
+
+Build the managed projects
+--------------------------
+
+The `Linux.Host`, while poorly named, is the cross-platform host for
+PowerShell targetting .NET Core. It is the top level project, so
+`dotnet publish` transitively builds all its dependencies, and emits a
+`powershell` executable and all necessary libraries (both native and
+managed) in a flat directory (specified with `--output`, otherwise
+automatically nested depending on runtime, configuration, and
+framework, see [issue #685][]). The `--configuration Linux` flag is
+necessary to ensure that the preprocessor definition `LINUX` is
+defined (see [issue #673][]).
+
+```sh
+dotnet restore
+dotnet publish --output bin --configuration Linux src/Microsoft.PowerShell.Linux.Host
+```
+
+PowerShell and all necessary components should now be in the `bin` folder.
+
+[issue #673]: https://github.com/PowerShell/PowerShell/issues/673
+[issue #685]: https://github.com/PowerShell/PowerShell/issues/685