Update instructions with more detail

Author: shana

docs/contributing/how-to-build.md

@@ -1,32 +1,56 @@
 # Contributing to GitHub for Unity
 
 ## Build Requirements
-- To build GitHub for Unity we recommend using Visual Studio 2015 or Mono 4.x and bash.
-- Building from the command line or from Visual Stuido requires referencing Unity DLLs
-  - Windows: `C:\Program Files (x86)\Unity\`
-  - macOS: `\Applications\Unity\`
-- Alternatively `UnityEditor.dll` and `UnityEngine.dll` can be copied to `.\script\lib`
+
+This repository is LFS-enabled. To clone it, you should use a git client that supports git LFS 2.x and submodules.
+
+### Windows
+
+- Visual Studio 2015+ or Mono 4.x + bash shell (git bash). Mono 5.x will not work
+- `UnityEngine.dll` and `UnityEditor.dll`.
+  - If you've installed Unity in the default location of `C:\Program Files\Unity` or `C:\Program Files (x86)\Unity`, the build will be able to reference these DLLs automatically. Otherwise, you'll need to copy these DLLs from your Unity installation into the `lib` directory in order for the build to work
+
+### MacOS
+
+- Mono 4.x. Mono 5.x will likely not work
+- `UnityEngine.dll` and `UnityEditor.dll`.
+  - If you've installed Unity in the default location of `/Applications/Unity`, the build will be able to reference these DLLs automatically. Otherwise, you'll need to copy these DLLs from your Unity installation into the `lib` directory in order for the build to work
+
+## Solution organization
+
+The `GitHub.Unity.sln` solution includes several projects:
+
+- dotnet-httpclient35 and octokit: external dependencies for threading and github api support, respectively. These are the submodules.
+- packaging: empty projects with build rules that copy DLLs to various locations for testing
+- Tests: unit and integration test projects
+- GitHub.Logging: A logging helper library
+- GitHub.Api: The core of the extension. This project is C#6 and includes async/await threading and other features that Unity cannot currently compile.
+- GitHub.Unity: Unity-specific code. This project is compilable by Unity
 
 ## How to Build
 
-Clone the repository and its submodules in a git GUI client or via the command line:
+Clone the repository and its submodules in a git GUI client that supports Git LFS or via the command line with the following commands
 
 ```
-git clone https://github.com/github-for-unity/Unity
+git lfs clone https://github.com/github-for-unity/Unity
 cd Unity
 git submodule init
 git submodule deinit script
 git submodule update
 ```
-    
+
 ### Visual Studio
 
 To build with Visual Studio 2015 open the solution file `GitHub.Unity.sln`. Select `Build Solution` in the `Build` menu.
 
-### Mono and Bash
+### Mono and Bash (windows and mac)
 
 To build with Mono 4.x and Bash execute `build.sh` in a bash shell.
 
 ## Build Output
 
-Building the project creates an output folder named `github-unity-test` that is a sibling to the cloned repository. For instance, if the solution is located at `c:\Projects\Unity` the test output can be foud at `c:\Projects\github-unity-test`. The output folder contains a blank Unity project folder named `GitHubExtensionProject`. This folder is a blank Unity 5.5 project with GitHub for Unity installed.
+Once you've built the solution for the first time, you can open `src/UnityExtension/Assets/Editor/GitHub.Unity` in Unity. This folder contains the `GitHub.Unity` project and all the Unity UI and other Unity-specific code that you can have Unity compile as normal for quick testing and prototyping.
+
+The build also creates a Unity test project called `GitHubExtension` inside a directory called `github-unity-test` next to your local clone. For instance, if the repository is located at `c:\Projects\Unity` the test project will be at `c:\Projects\github-unity-test\GitHubExtension`. You can use this project to test binary builds of the extension in a clean environment (all needed DLLs will be copied to it every time you build).
+
+Note: some files might be locked by Unity if have one of the build output projects open when you compile from VS or the command line. This is expected and shouldn't cause issues with your builds.