diff --git a/docs/developers-guide.md b/docs/developers-guide.md
index cf3ff54d2881f70db0a74a4082ca56da11683cce..64958e5cfc3df9b13f9bf64769df6d3e81792d98 100644
--- a/docs/developers-guide.md
+++ b/docs/developers-guide.md
@@ -14,6 +14,11 @@ For significant feature additions, it is expected that discussion will have take
 
 We don't like getting sued, so before merging any pull request, we'll need each person contributing code to sign a Contributor License Agreement [here](https://docs.google.com/a/metabase.com/forms/d/1oV38o7b9ONFSwuzwmERRMi9SYrhYeOrkbmNaq9pOJ_E/viewform)
 
+# Development on Windows
+
+The development scripts are designed for Linux/Mac environment, so we recommend using the latest Windows 10 version with [WSL (Windows Subsystem for Linux)](https://msdn.microsoft.com/en-us/commandline/wsl/about) and [Ubuntu on Windows](https://www.microsoft.com/store/p/ubuntu/9nblggh4msv6). The Ubuntu Bash shell works well for both backend and frontend development.
+
+If you have problems with your development environment, make sure that you are not using any development commands outside the Bash shell. As an example, Node dependencies installed in normal Windows environment will not work inside Ubuntu Bash environment.
 
 # Install Prerequisites
 
@@ -24,6 +29,7 @@ These are the set of tools which are required in order to complete any build of
 3. [Yarn package manager for Node.js](https://yarnpkg.com/)
 3. [Leiningen (http://leiningen.org/)](http://leiningen.org/)
 
+If you are developing on Windows, make sure to use Ubuntu on Windows and follow instructions for Ubuntu/Linux instead of installing ordinary Windows versions.
 
 # Build Metabase
 
@@ -70,13 +76,6 @@ Start the frontend build process with
 
     yarn run build-hot
 
-Caveat - Yarn does not properly support `build-hot` on Windows 8/10. You will need to manually build the frontend client with
-    
-    yarn run build
-
-This will get you a full development server running on port :3000 by default.
-
-
 ## Frontend development
 We use these technologies for our FE build process to allow us to use modules, es6 syntax, and css variables.