Improve the readme

Sanded it down, varnished, sprinkled liberally with truffle oil, and added more cowbell.

README.md

@@ -8,18 +8,44 @@ Direct2D, and integrates seamlessly with XAML and ICoreWindow.
 Windows Canvas is work in progress and evolving rapidly. The goal of releasing this code 
 in an early, incomplete state is to solicit early developer feedback.
 
-More information can be found on the [blog](http://blogs.msdn.com/b/windowscanvas/).
+- [Features](http://github.com/Microsoft/WindowsCanvas/wiki/Features) - *what's implemented so far*
+- [Backlog](http://github.com/Microsoft/WindowsCanvas/wiki/Backlog) - *what we plan to add next*
+- [Documentation](http://microsoft.github.io/WindowsCanvas)
+- [Team blog](http://blogs.msdn.com/b/windowscanvas)
+- [License](http://www.apache.org/licenses/LICENSE-2.0.html)
+- [Contributing](http://github.com/Microsoft/WindowsCanvas/blob/master/CONTRIBUTING)
+
+## Code Example
+To give you a flavor of what the code looks like, here is a snippet of XAML:
+```xml
+xmlns:canvas="using:Microsoft.Graphics.Canvas"
+
+<Grid>
+    <canvas:CanvasControl x:Name="canvasControl" />
+</Grid>
+```
+and C#:
+```cs
+canvasControl.Draw += canvasControl_Draw; 
+```
+```cs
+void canvasControl_Draw(CanvasControl sender, CanvasDrawEventArgs args)
+{
+    args.DrawingSession.Clear(Colors.BlueViolet);
+}
+```
 
 ## Setup
-### Visual Studio
+#### Visual Studio
 - Download [here](http://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx)
-- Visual Studio 2013 Update 2 required
+- Requires Visual Studio 2013 Update 2 or greater
+- If using Visual Studio Express, requires the 'for Windows' version (not 'for Windows Desktop')
 
-### Clone Repository
+#### Clone Repository
 - Go to 'View' -> 'Team Explorer' -> 'Local Git Repositories' -> 'Clone'
 - Add the Windows Canvas repository URL (https://github.com/Microsoft/WindowsCanvas.git) and hit 'Clone'
 
-### Build NuGet Packages
+#### Build NuGet Packages
 - In Windows search, type 'Visual Studio Tools', and select that folder to open it
 - Launch 'Developer Command Prompt for VS2013'
 - Change directory to your cloned Windows Canvas repository and run 'build'
@@ -32,11 +58,9 @@ More information can be found on the [blog](http://blogs.msdn.com/b/windowscanva
   - Click the 'Update' button
   - Click 'OK'
 
-## Quickstart
+#### Quickstart
 Follow the steps below to get started on writing your own apps.
  
-A working sample can be found in the Samples directory.
-
 - Go to 'File' -> 'New' -> 'Project...'
 - Select 'Visual C#' -> 'Store Apps' -> 'Universal Apps'
 - Create a 'Blank App (Universal Apps)'
@@ -48,66 +72,43 @@ A working sample can be found in the Samples directory.
 - Change Solution platform from 'Any CPU' to x86
 - You are now ready to hit F5 (Build)
 
-## Code Example
-To give you a flavor of what the code looks like, here is a snippet:
-```cs
-canvasControl.Draw += canvasControl_Draw; 
-...
-void canvasControl_Draw(CanvasControl sender, CanvasDrawEventArgs args)
-{
-    args.DrawingSession.Clear(Colors.BlueViolet);
-}
-```
+A working sample can be found in the Samples directory.
 
-## Resources
+## Source Directory Structure
 
-### Project Backlog
-- https://github.com/Microsoft/WindowsCanvas/wiki
-
-### License
-- [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)
-
-### Contributions
-- Check out CONTRIBUTING in the root folder
-
-## Windows Canvas Directory Structure
-
-**Note: For the bulk of interesting product code, go to /winrt/lib.**
+Note: For the bulk of interesting product code, go to /winrt/lib.
 
 **/bin** - Binary files generated by the build
 
 **/build** - Shared, build-related resources that are common across projects
-
 - /Assets - Common Windows Store assets used for tests and samples
 - /nuget - Resources needed for building the NuGet package
 
-**/numeric** - Cross-platform vector and matrix library. There are three implementations:
+**/numerics** - Cross-platform vector and matrix math library. There are three implementations:
 - /Cpp
 - /DotNet
 - /WinRT
 
-**/obj** - All intermediate object files generated during a build
+**/obj** - Intermediate files generated by the build
 
 **/samples** - Example projects showing how to use Windows Canvas
 
 **/tests** - Test projects that consume Windows Canvas in a similar way to how an 
 external customer would. Each one is a Windows Store app. These tests are run for manual 
 verification.
-- /CppConsumer
-- /CsConsumer
-- /ExampleGallery
 
 **/tools** - Standalone utilities, separate from Canvas product code
 - /codegen - Generates headers+IDL from XML resource files (you don't have to build this to build Windows Canvas)
 - /copyright - Verifies the right copyright banner appears at the top of each source file
+- /docs - Tools and scripts for building API reference documentation
 
 **/winrt** - Windows Canvas product code and automated tests
 - /dll - Build resources for the product dll
+- /docsrc - Source files used to create the reference documentation
 - /inc - Common includes
 - /lib - All the projected IDL and runtime class implementations!
   - /WinRTDirectX - projections for D3D/DXGI types
-- /published - Contains headers included in the NuGet package that are required to use Windows Canvas
-- /test.internal - Automated tests that link directly with winrt.lib to access internals of the implementation
+- /published - Headers that are included directly in the NuGet package for 3rd part consumption
 - /test.external - Automated tests that use only the public WinRT interface
-
-
+- /test.internal - Automated tests that link directly with winrt.lib to access internals of the implementation
+- /test.managed - Automated tests written in C#