Convert wiki to docs

25 files changed, 186 insertions, 47 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c624f4f77b..e1f9afc3f8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,11 +1,7 @@
 # Contributing
 
-See [Contributing] on the wiki for information about coding styles, source structure, making
-pull requests, and more.
+See [Contributing](Documentation/contributing.md) for information about coding styles, source structure, making pull requests, and more.
 
-[Contributing]: https://github.com/dotnet/corefx/wiki/Contributing
 # Developers
 
-See the [Developer Guide] for details about developing in this repo.
-
-[Developer Guide]: https://github.com/dotnet/corefx/wiki/Developer-Guide
+See the [Developer Guide](Documentation/developer-guide.md) for details about developing in this repo.
diff --git a/Documentation/README.md b/Documentation/README.md
new file mode 100644
index 0000000000..1b059c0ba3
--- /dev/null
+++ b/Documentation/README.md
@@ -0,0 +1,58 @@
+Documents Index
+===============
+
+Learn about .NET Core
+====================
+
+- [Brief Intro to .NET Core](https://github.com/dotnet/coreclr/blob/master/Documentation/dotnetcore-intro.md)
+- [[WIP] Official .NET Core Docs](http://dotnet.readthedocs.org)
+
+Get .NET Core
+=============
+
+- [Get .NET Core DNX SDK on Windows](https://github.com/dotnet/coreclr/blob/master/Documentation/get-dotnetcore-dnx-windows.md)
+- [Get .NET Core DNX SDK on OS X](https://github.com/dotnet/coreclr/blob/master/Documentation/get-dotnetcore-dnx-osx.md)
+- [Get .NET Core DNX SDK on Linux](https://github.com/dotnet/coreclr/blob/master/Documentation/get-dotnetcore-dnx-linux.md)
+- [Get .NET Core (Raw) on Windows](https://github.com/dotnet/coreclr/blob/master/Documentation/get-dotnetcore-windows.md)
+
+Project Docs
+============
+
+- [Developer Guide](developer-guide.md)
+- [Project priorities](https://github.com/dotnet/coreclr/blob/master/Documentation/project-priorities.md)
+- [Contributing to CoreFX](contributing.md)
+- [Contributing to .NET Core](https://github.com/dotnet/coreclr/blob/master/Documentation/contributing.md)
+- [Contributing Workflow](https://github.com/dotnet/coreclr/blob/master/Documentation/contributing-workflow.md)
+- [Issue Guide](issue-guide.md)
+- [Branching Guide](branching-guide.md)
+- [API Review Process](api-review-process.md)
+- [Strong Name Signing](strong-name-signing.md)
+- [Open Source Signing](oss-signing.md)
+- [Repo Organization](repo-organization.md)
+
+Coding Guidelines
+=================
+
+- [C# coding style](coding-style.md)
+- [Framework Design Guidelines](framework-design-guidelines-digest.md)
+- [Cross-Platform Guidelines](cross-platform-guidelines.md)
+- [Performance Guidelines](performance-guidelines.md)
+- [Interop Guidelines](interop-guidelines.md)
+- [Breaking Changes](breaking-changes.md)
+- [Breaking Change Definitions](breaking-change-definitions.md)
+- [Breaking Change Rules](breaking-change-rules.md)
+
+Building from Source
+====================
+
+- [Building on Linux](linux-instructions.md)
+- [Code Coverage](code-coverage.md)
+
+Other Information
+=================
+
+- [CoreCLR Repo documentation](https://github.com/dotnet/coreclr/tree/master/Documentation)
+- [Porting to .NET Core](support-dotnet-core-instructions.md)
+- [.NET Standards (Ecma)](https://github.com/dotnet/coreclr/blob/master/Documentation/dotnet-standards.md)
+- [MSDN Entry for the CLR](http://msdn.microsoft.com/library/8bs2ecf4.aspx)
+- [Wikipedia Entry for the CLR](http://en.wikipedia.org/wiki/Common_Language_Runtime)
diff --git a/API-Review-Process.md b/Documentation/api-review-process.md
index 6dfc6e50ca..3bc6991771 100644
--- a/API-Review-Process.md
+++ b/Documentation/api-review-process.md
@@ -1,3 +1,6 @@
+API Review Process
+==================
+
 The .NET Framework has a long standing history of taking API usability extremely seriously. Thus, we generally review every single API that is added to the product. This page discusses how we conduct API reviews for components that are open sourced.
 
 ## Process Goals
@@ -18,7 +21,7 @@ For trivial code changes, such as typo fixes, we want folks to directly submit a
 
 For work that involves adding new APIs we'd like the issue to contain what we call a *speclet*. The speclet should provide a rough sketch of how the APIs are intended to be used, with sample code that shows typical scenarios. The goal isn't to be complete but rather to illustrate the direction so that readers can judge whether the proposal is sound. Here is [a good example](https://github.com/dotnet/corefx/issues/271).
 
-![API Review Process](img/API-Review-Process.png)
+![API Review Process](images/api-review-process.png)
 
 ## Steps
 
@@ -30,7 +33,7 @@ For work that involves adding new APIs we'd like the issue to contain what we ca
 
 * **Coding**. The contributor is implementing the APIs as discussed. Minor deviations are OK, but if during the implementation the design starts to take a major shift, the contributor is encouraged to go back to the issue and raise the concerns with the current proposal.
 
-* **Pull request is being created**. Once the contributor believes the implementation is ready for review, she creates a pull request, referencing the issue created in the first step. In order to call dips, you can also create the PR before it's completely ready. Use checkboxes to indicate which areas are still missing so that we know it's not ready for review yet. [Here is a good example](https://github.com/dotnet/corefx/pull/316). At this time, if any new API are being added to a type that has shipped in the full .NET Framework, submit the pull request to the *future* branch. See [[Branching Guide]].
+* **Pull request is being created**. Once the contributor believes the implementation is ready for review, she creates a pull request, referencing the issue created in the first step. In order to call dips, you can also create the PR before it's completely ready. Use checkboxes to indicate which areas are still missing so that we know it's not ready for review yet. [Here is a good example](https://github.com/dotnet/corefx/pull/316). At this time, if any new API are being added to a type that has shipped in the full .NET Framework, submit the pull request to the *future* branch. See [Branching Guide](branching-guide.md).
 
 * **Pull request is being reviewed**. The community reviews the code for the pull request. The review should focus on the code changes and architecture - not the APIs themselves. Once at least two project owners give their OK, the PR is considered good to go.
 
diff --git a/Branching-Guide.md b/Documentation/branching-guide.md
index 59f6bead3d..b67a65d751 100644
--- a/Branching-Guide.md
+++ b/Documentation/branching-guide.md
@@ -1,3 +1,6 @@
+Branching Guide
+===============
+
 We will have the following branches in the corefx repository:
 
 * **master**
@@ -21,5 +24,3 @@ We will have the following branches in the corefx repository:
  * Submit PRs here only if you've made prior arrangements to work on something in one of these branches.
  * It is up to the developers creating these branches to decide what level of review is required
  * These features will only ship if they are successfully pulled to master or future via the standard PR and API review process.
-
-
diff --git a/Breaking-Change-Definitions.md b/Documentation/breaking-change-definitions.md
index 0992830a2f..7c34f866d8 100644
--- a/Breaking-Change-Definitions.md
+++ b/Documentation/breaking-change-definitions.md
@@ -1,24 +1,38 @@
+Breaking Change Definitions
+===========================
+
+Behavioral Change
+-----------------
 
-**Behavioral Change**  
 A behavioral change represents changes to the behavior of a member. A behavioral change may including throwing a new exception, adding or removing internal method calls, or alternating the way in which a return value is calculated. Behavioral changes can be the hardest type of change to categorize as acceptable or not - they can be severe in impact, or relatively innocuous.
 
-**Binary Compatibility**  
+Binary Compatibility  
+--------------------
+
 Refers to the ability of existing consumers of an API to be able to use a newer version without recompilation. By definition, if an assembly's public signatures have been removed, or altered so that consumers cannot no longer access the same interface exposed by the assembly, the change is said to be a _binary incompatible change_.
 
-**Source Compatibility**  
+Source Compatibility
+--------------------
+
 Refers to the ability of existing consumers of an API to recompile against a newer version without any source changes. By definition, if a consumer needs to make changes to its code in order to for it build successfully against a newer version of an API, the change is said to be a _source incompatible change_.
 
-**Design-Time Compatibility**  
+Design-Time Compatibility  
+-------------------------
+
 _Design-time compatibility_ refers to preserving the design-time experience across versions of Visual Studio and other design-time environments. This can involve details around the UI of the designer, but by far the most interesting design-time compatibility is project compatibility. A potential project (or solution), must be able to be opened, and used on a newer version of a designer.
 
-**Backwards Compatibility**  
+Backwards Compatibility  
+-----------------------
+
 _Backwards compatibility_ refers to the ability of an existing consumer of an API to run against, and behave in the same way against a newer version. By definition, if a consumer is not able to run, or behaves differently against the newer version of the API, then the API is said to be _backwards incompatible_. 
 
 Changes that affect backwards compatibility are strongly discouraged. All alternates should be actively considered, since developers will, by default, expect backwards compatibility in newer versions of an API.
 
-**Forwards Compatibility**  
+Forwards Compatibility  
+----------------------
+
 _Forwards compatibility_ is the exact reverse of backwards compatibility; it refers to the ability of an existing consumer of an API to run against, and behave in the way against a _older_ version. By definition, if a consumer is not able to run, or behaves differently against an older version of the API, then the API is said to be _forwards incompatible_.
 
 Changes that affect forwards compatibility are generally less pervasive, and there is not as stringent a demand to ensure that such changes are not introduced. Customers accept that a consumer which relies upon a newer API, may not function correctly against the older API.
 
-This wiki does not attempt to detail forwards incompatibilities.
+This document does not attempt to detail forwards incompatibilities.
diff --git a/Breaking-Change-Rules.md b/Documentation/breaking-change-rules.md
index 342f8c23db..27a5d64dba 100644
--- a/Breaking-Change-Rules.md
+++ b/Documentation/breaking-change-rules.md
@@ -1,4 +1,5 @@
-## Table of Contents
+Breaking Change Rules
+=====================
 
 * [Behavioral Changes](#behavioral-changes)
    * [Property, Field, Parameter and Return Values](#property-field-parameter-and-return-values)
diff --git a/Breaking-Changes.md b/Documentation/breaking-changes.md
index 5394baffc8..1f6b1d0609 100644
--- a/Breaking-Changes.md
+++ b/Documentation/breaking-changes.md
@@ -1,3 +1,6 @@
+Breaking Changes
+================
+
 We take compatibility in the .NET Framework and .NET Core extremely seriously.
 
 Although .NET Core can be deployed app local, we are engineering it such that portable libraries can target it and still run on the full desktop framework as well. This means that the behavior of the full .NET Framework constrains the implementation of any overlapping API in .NET Core.
@@ -56,4 +59,4 @@ This bucket is painful for the machine-wide .NET Framework, but we do have much
 * All bucket 1, 2, and 3 breaking changes require talking to the repo owners first.
 * If you're not sure in which bucket applies to a given change, contact us as well.
 * It doesn't matter if the old behavior is "wrong", we still need to think through the implications.
-* If a change is deemed too breaking, we can help identify alternatives such as introducing a new API and obsoleting the old one.
\ No newline at end of file
+* If a change is deemed too breaking, we can help identify alternatives such as introducing a new API and obsoleting the old one.
diff --git a/Code-Coverage.md b/Documentation/code-coverage.md
index ac1d383ca3..4d9467241c 100644
--- a/Code-Coverage.md
+++ b/Documentation/code-coverage.md
@@ -1,4 +1,5 @@
-## Overview
+Code Coverage
+=============
 
 "Code coverage" is a measure that indicates how much of our library code is exercised by our test suites.  We measure code coverage using the [OpenCover](https://github.com/opencover/opencover), and a report of our latest code coverage results can be seen by clicking the coverage badge on the [CoreFX home page](https://github.com/dotnet/corefx):
 
diff --git a/Coding-style.md b/Documentation/coding-style.md
index 6f0c8f57ce..a909488c69 100644
--- a/Coding-style.md
+++ b/Documentation/coding-style.md
@@ -1,7 +1,8 @@
-## General guidelines
+C# Coding Style
+===============
+
 For non .cs files (c++, xml etc) our current best guidance is consistency. When editing files, keep new code and changes consistent with the style in the files. For new files, it should conform to the style for that component. Last, if there's a completely new component, anything that is reasonably broadly accepted is fine.
 
-## C# guidelines
 The general rule we follow is "use Visual Studio defaults".
 
 1. We use [Allman style](http://en.wikipedia.org/wiki/Indent_style#Allman_style) braces, where each brace begins on a new line. A single line statement block can go without braces but the block must be properly indented on its own line and it must not be nested in other statement blocks that use braces (See issue [381](https://github.com/dotnet/corefx/issues/381) for examples). 
@@ -124,4 +125,4 @@ namespace System.Collections.Generics
         ...
     }
 }
-```
\ No newline at end of file
+```
diff --git a/Documentation/contributing.md b/Documentation/contributing.md
new file mode 100644
index 0000000000..25ded4a1a2
--- /dev/null
+++ b/Documentation/contributing.md
@@ -0,0 +1,17 @@
+Contributing to CoreFX
+======================
+
+This document describes contribution guidelines that are specific to CoreFX. Please read [.NET Core Guidelines](https://github.com/dotnet/coreclr/blob/master/Documentation/contributing.md) for more general .NET Core contribution guidelines.
+
+Coding Style Changes
+--------------------
+
+We intend to bring dotnet/corefx in to full conformance with the style guidelines described in [Coding Style](coding-style.md). We plan to do that with tooling, in a holistic way. In the meantime, please:
+
+* **DO NOT** send PRs for style changes. 
+* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
+
+API Changes
+-----------
+
+* **DON'T** submit API additions to any type that has shipped in the full .NET framework to the *master* branch. Instead, use the *future* branch. See [Branching Guide](branching-guide.md).
diff --git a/Cross-Platform-Code-Guidelines.md b/Documentation/cross-platform-guidelines.md
index a655da8aaa..bcb02bb56c 100644
--- a/Cross-Platform-Code-Guidelines.md
+++ b/Documentation/cross-platform-guidelines.md
@@ -1,4 +1,7 @@
-This page provides a FAQ for how we handle cross-platform code in CoreFX. (For structuring of interop code, see [[Structuring Interop Code]].)
+Cross-Platform Guidelines
+=========================
+
+This page provides a FAQ for how we handle cross-platform code in CoreFX. (For structuring of interop code, see [interop guidelines](interop-guidelines.md).)
 
 #### Should assemblies be binary-compatible across platforms (e.g. exact same System.IO.dll on Windows, Linux, and Mac)?
 
@@ -22,4 +25,4 @@ When the whole type is for a particular platform, we've been using the prefix, e
 
 #### When should define statements be used rather than including different source files in the build environment?
 
-We're striving to avoid defines whenever possible, instead preferring to include just the source files that are relevant.
\ No newline at end of file
+We're striving to avoid defines whenever possible, instead preferring to include just the source files that are relevant.
diff --git a/Documentation/developer-guide.md b/Documentation/developer-guide.md
new file mode 100644
index 0000000000..34f5529811
--- /dev/null
+++ b/Documentation/developer-guide.md
@@ -0,0 +1,18 @@
+Developer Guide
+===============
+
+This guide provides instructions (mostly as links) on how to build the repo and implement improvements. It will expand over time.
+
+Building the repository
+=======================
+
+The CoreFX repo can be built from a regular, non-admin command prompt. The build produces multiple managed binaries that make up the CoreFX libraries and the accompanying tests. The repo can be built for the following platforms, using the provided instructions.
+
+| Chip  | Windows | Linux | OS X |
+| :---- | :-----: | :---: | :--: |
+| x64   | ●| ◒| ◒ |		  
+| x86   | ◯| ◯| ◯|
+| ARM32 | ◯ | ◯| ◯ |
+|       | [Instructions](windows-instructions.md) | [Instructions](linux-instructions.md) | |  
+
+The CoreFX build and test suite is a work in progress, as are the [building and testing instructions](README.md). The .NET Core team and the community are improving Linux and OS X support on a daily basis are and adding more tests for all platforms. See [CoreFX Issues](https://github.com/dotnet/corefx/issues) to find out about specific work items or report issues.
diff --git a/Framework-Design-Guidelines-Digest.md b/Documentation/framework-design-guidelines-digest.md
index f9674e4538..1337ad8461 100644
--- a/Framework-Design-Guidelines-Digest.md
+++ b/Documentation/framework-design-guidelines-digest.md
@@ -1,4 +1,5 @@
-# Introduction
+Framework Design Guidelines - Digest
+====================================
 
 This page is a distillation and a simplification of the most basic
 guidelines described in detail in a book titled
@@ -309,4 +310,4 @@ conformance to the [Framework Design Guidelines][FDG].
 ## Presentations
 
 * [Overview of the Framework Design Guidelines](http://blogs.msdn.com/kcwalina/archive/2007/03/29/1989896.aspx)
-* [TechEd 2007 Presentation about framework engineering](http://blogs.msdn.com/kcwalina/archive/2008/01/08/FrameworkEngineering.aspx)
\ No newline at end of file
+* [TechEd 2007 Presentation about framework engineering](http://blogs.msdn.com/kcwalina/archive/2008/01/08/FrameworkEngineering.aspx)
diff --git a/img/API-Review-Process.png b/Documentation/images/api-review-process.png
index f6203aff32..f6203aff32 100644
--- a/img/API-Review-Process.png
+++ b/Documentation/images/api-review-process.png
diff --git a/Structuring-Interop-Code.md b/Documentation/interop-guidelines.md
index 3926018be3..edb3936cd2 100644
--- a/Structuring-Interop-Code.md
+++ b/Documentation/interop-guidelines.md
@@ -1,3 +1,6 @@
+Interop Guidelines
+==================
+
 ## Goals
 We have the following goals related to interop code being used in CoreFX:
 
diff --git a/Issue-Guide.md b/Documentation/issue-guide.md
index 2ff4d8cc1f..a1f669a2a7 100644
--- a/Issue-Guide.md
+++ b/Documentation/issue-guide.md
@@ -1,4 +1,6 @@
-### Overview
+Issue Guide
+===========
+
 This page outlines how the CoreFx team thinks about and handles issues.  For us, issues on GitHub represent actionable work that should be done at some future point.  It may be as simple as a small product or test bug or as large as the work tracking the design of a new feature.  However, it should be work that falls under the charter of CoreFx, which is a collection of foundational libraries that make up the .NET Core development stack.  We will keep issues open even if the CoreFx team internally has no plans to address them in an upcoming release, as long as we consider the issue to fall under our purview.
 
 ### When we close issues
@@ -8,7 +10,7 @@ As noted above, we don't close issues just because we don't plan to address them
 2. Cross cutting work better suited for another team.  Sometimes the line between the framework, languages and runtime blurs.  For some issues, we may feel that the work is better suited for the runtime team, language team or other partner.  In these cases, we'll close the issue and open it with the partner team.  If they end up not deciding to take on the issue, we can reconsider it here.
 3. Nebulous and Large open issues.  Large open issues are sometimes better suited for [User Voice](http://visualstudio.uservoice.com/forums/121579-visual-studio/category/31481--net), especially when the work will cross the boundaries of the framework, language and runtime.  A good example of this is the SIMD support we recently added to CoreFx.  This started as a User Voice request, and eventually turned into work for both the core libraries and runtime.
 
-Sometimes after debate, we'll decide an issue isn't a good fit for CoreFx.  In that case, we'll also close it.  Because of this, we ask that you don't start working on an issue until it's tagged with "up for grabs" or "feature approved".  We'd hate for you to spend time and effort working on a change we'll ultimately be unable to take.
+Sometimes after debate, we'll decide an issue isn't a good fit for CoreFx.  In that case, we'll also close it.  Because of this, we ask that you don't start working on an issue until it's tagged with "up for grabs" or "feature approved".  Both you and the team will be unhappy if you spend time and effort working on a change we'll ultimately be unable to take. We try to avoid that.
 
 ### Labels
 We use GitHub labels on our issues in order to classify them.  We have the following categories per issue:
diff --git a/Building-On-Unix.md b/Documentation/linux-instructions.md
index c3eb496b00..fe625fb305 100644
--- a/Building-On-Unix.md
+++ b/Documentation/linux-instructions.md
@@ -1,5 +1,7 @@
-# General Information
-CoreFx can be built on top of current [Mono CI builds](https://github.com/dotnet/corefx/wiki/Building-On-Unix#installing-mono-packages) or a direct [build/install of Mono](http://www.mono-project.com/docs/compiling-mono/). It builds using MSBuild and Roslyn and requires changes that have not yet made it to official released builds.
+Building CoreFX on Linux
+========================
+
+CoreFx can be built on top of current [Mono CI builds](#installing-mono-packages) or a direct [build/install of Mono](http://www.mono-project.com/docs/compiling-mono/). It builds using MSBuild and Roslyn and requires changes that have not yet made it to official released builds.
 
 After preparing Mono, clone if you haven't already, and run the build script.
 
@@ -73,4 +75,4 @@ System.Diagnostics.FileVersionInfo.Tests.csproj does not build on Unix. https://
 
 System.Diagnostics.Debug.Tests does not build on Unix. https://github.com/dotnet/corefx/issues/1609
 
-Mono fails when trying to get custom attributes on CoreFx assemblies. https://bugzilla.xamarin.com/show_bug.cgi?id=29679
\ No newline at end of file
+Mono fails when trying to get custom attributes on CoreFx assemblies. https://bugzilla.xamarin.com/show_bug.cgi?id=29679
diff --git a/Open-Source-Signing.md b/Documentation/oss-signing.md
index 8bfd7cfe10..2e8616f9e8 100644
--- a/Open-Source-Signing.md
+++ b/Documentation/oss-signing.md
@@ -1,4 +1,7 @@
-For reasons listed over on [Strong Naming](Strong Naming), all .NET Core assemblies are strong-named.
+Open Source Signing
+===================
+
+For reasons listed over on [Strong Naming](strong-name-signing.md), all .NET Core assemblies are strong-named.
 
 To enable you to build assemblies that have a matching identity to what Microsoft would build, we leverage a new signing mechanism called _Open Source Signing (OSS)_. This lets you clone the dotnet/corefx repository, build and then drop the resulting assembly in your application with zero changes to consuming libraries. By default, all .NET Core projects build using OSS.
 
@@ -12,4 +15,4 @@ Known issues when debugging and testing OSS assemblies on .NET Framework:
 
 - You will not be able to install the assembly to the [Global Assembly Cache (GAC)](https://msdn.microsoft.com/en-us/library/yf1d93sz.aspx)
 - You will not be able to load the assembly in an AppDomain where shadow copying is turned on.
-- You will not be able to load the assembly in a partially trusted AppDomain
\ No newline at end of file
+- You will not be able to load the assembly in a partially trusted AppDomain
diff --git a/Performance.md b/Documentation/performance-guidelines.md
index 4fd276b872..477c8a9e6a 100644
--- a/Performance.md
+++ b/Documentation/performance-guidelines.md
@@ -1,12 +1,15 @@
+Managed Code Performance Guidelines
+===================================
+
 Different applications have different needs when it comes to performance.  For libraries that may be used in any of them and potentially on critical paths, however, it is of the utmost importance that code is as efficient as possible.  The code in CoreFX should strive to be high-performing, including minimizing the number and size of allocations, minimizing the number of branches involved in code, and overall minimizing the amount of work that must be done to perform any given operation.
 
 Much has been written about writing high-performance code in C#.  This page provides links to some of that material and will expand over time as additional resources are found and identified as being relevant and useful.
 
-CoreCLR performance guidelines are available [here](https://github.com/dotnet/coreclr/wiki/Performance).
+You can read [CoreCLR Performance Requirements](https://github.com/master/coreclr/blob/master/Documentation/performance-requirements.md) to learn more.
 
 # Memory Management
 
-* **Avoiding delegate and closure allocations for lambdas**.  The code generated by the C# compiler for anonymous methods and lambdas may involve one or more allocations.  Certain patterns in APIs can help to avoid these allocations.  See this [blog post](http://blogs.msdn.com/b/pfxteam/archive/2012/02/03/10263921.aspx) for more information.
+* **Avoiding delegate and closure allocations for lambdas**.  The code generated by the C# compiler for anonymous methods and lambdas may involve one or more allocations.  Certain patterns in APIs can help to avoid these allocations.  See [Know Thine Implicit Allocations](http://blogs.msdn.com/b/pfxteam/archive/2012/02/03/10263921.aspx) for more information.
 
 # Asynchrony
 
diff --git a/Test-Orgnaization.md b/Documentation/repo-organization.md
index db8c5828fc..686db5b0c3 100644
--- a/Test-Orgnaization.md
+++ b/Documentation/repo-organization.md
@@ -1,3 +1,6 @@
+Repo Organization
+=================
+
 Tests for a project are kept under the `tests` folder, which is a peer of the `src` folder.  If you need to have multiple test projects for a component, structure them in sub folders.
 
 For example, lay things out like this:
@@ -26,4 +29,4 @@ tests\
     test_folder_2\
         test_1.cs
         test_2.cs
-```
\ No newline at end of file
+```
diff --git a/Strong-Naming.md b/Documentation/strong-name-signing.md
index 1f3d4708ae..ce3543fde9 100644
--- a/Strong-Naming.md
+++ b/Documentation/strong-name-signing.md
@@ -1,3 +1,6 @@
+Strong Name Signing
+===================
+
 All .NET Core assemblies are [strong-named](http://msdn.microsoft.com/en-us/library/wd40t7ad.aspx). We do this for two reasons:
 
 1. _Compatibility_. We want to maintain type identity with previous versions of our assemblies that have shipped across various versions of our platforms. Removing a strong-name from an assembly is a breaking change, and would break the ability to consume and run libraries built against the previous identities.
@@ -18,4 +21,4 @@ There are three major problems that developers run into after strong naming thei
 
 2. _Virality_. Once you've strong-named an assembly, you can only statically reference other strong-named assemblies. 
 
-3. _No drop-in replacement_. This is a problem for open source libraries where the strong-name private key is not checked into the repository. This means that developers are unable to build to their own version of the library and then use it as a drop-in replacement without recompiling _all_ consuming libraries up stack to pick up the new identity. This is extremely problematic for libraries, such as Json.NET, which have large incoming dependencies. Firstly, we would recommend that these open source projects check-in their private key (remember, [strong-names are used for identity, and not for security](http://msdn.microsoft.com/en-us/library/wd40t7ad.aspx)). Failing that, however, we've introduced a new concept called [[Open Source Signing]] that enables developers to build drop-in replacements without needing access to the strong-name private key. This is the mechanism that .NET Core libraries use by default.
\ No newline at end of file
+3. _No drop-in replacement_. This is a problem for open source libraries where the strong-name private key is not checked into the repository. This means that developers are unable to build to their own version of the library and then use it as a drop-in replacement without recompiling _all_ consuming libraries up stack to pick up the new identity. This is extremely problematic for libraries, such as Json.NET, which have large incoming dependencies. Firstly, we would recommend that these open source projects check-in their private key (remember, [strong-names are used for identity, and not for security](http://msdn.microsoft.com/en-us/library/wd40t7ad.aspx)). Failing that, however, we've introduced a new concept called [Open Source Signing](oss-signing.md) that enables developers to build drop-in replacements without needing access to the strong-name private key. This is the mechanism that .NET Core libraries use by default.
diff --git a/Developer-Guide.md b/Documentation/windows-instructions.md
index 913f924746..6f4ff2617a 100644
--- a/Developer-Guide.md
+++ b/Documentation/windows-instructions.md
@@ -1,3 +1,6 @@
+Building CoreFX on Windows
+==========================
+
 You can build .NET Core either via the command line or by using Visual Studio.
 We currently only support building and running on Windows. Other platforms will
 come later.
@@ -18,7 +21,7 @@ the core tests for the project. Visual Studio Solution (.sln) files exist for
 related groups of libraries. These can be loaded to build, debug and test inside
 the Visual Studio IDE.
 
-[[Building On Unix]]
+[Building On Linux](linux-instructions.md)
 ## Tests
 
 We use the OSS testing framework [xunit](http://xunit.github.io/)
@@ -135,4 +138,4 @@ Code coverage reports from the continuous integration system are available from
 * VS 2015 is required to debug tests running on CoreCLR as the CoreCLR
 debug engine is a VS 2015 component.
 
-* If the Xamarin PCL profiles are installed, the build will fail due to [issue #449](https://github.com/dotnet/corefx/issues/449).  A possible workaround is listed [in the issue](https://github.com/dotnet/corefx/issues/449#issuecomment-95117040) itself.
\ No newline at end of file
+* If the Xamarin PCL profiles are installed, the build will fail due to [issue #449](https://github.com/dotnet/corefx/issues/449).  A possible workaround is listed [in the issue](https://github.com/dotnet/corefx/issues/449#issuecomment-95117040) itself.
diff --git a/README.md b/README.md
index a8de08a544..a135316e63 100644
--- a/README.md
+++ b/README.md
@@ -28,9 +28,9 @@ Want to get more familiar with what's going on in the code?
 
 Looking for something to work on? The list of [up-for-grabs issues](https://github.com/dotnet/corefx/labels/up%20for%20grabs) is a great place to start or for larger items see the list of [feature approved](https://github.com/dotnet/corefx/labels/feature%20approved). See some of our guides for more details:
 
-* [Contributing Guide](https://github.com/dotnet/corefx/wiki/Contributing)
-* [Developer Guide](https://github.com/dotnet/corefx/wiki/Developer-Guide)
-* [Issue Guide](https://github.com/dotnet/corefx/wiki/Issue-Guide)
+* [Contributing Guide](Documentation/contributing-corefx.md)
+* [Developer Guide](developer-guide.md)
+* [Issue Guide](issue-guide.md)
 
 You are also encouraged to start a discussion by filing an issue or creating a
 gist.
diff --git a/build.cmd b/build.cmd
index c0ec2f4513..2d58165e8b 100644
--- a/build.cmd
+++ b/build.cmd
@@ -18,7 +18,7 @@ if not defined VisualStudioVersion (
     )
 
     echo Error: build.cmd requires Visual Studio 2013 or 2015.  
-    echo        Please see https://github.com/dotnet/corefx/wiki/Developer-Guide for build instructions.
+    echo        Please see https://github.com/dotnet/corefx/blob/master/Documentation/developer-guide.md for build instructions.
     exit /b 1
 )
 
diff --git a/build.sh b/build.sh
index a03874bab4..821e4d9cf0 100755
--- a/build.sh
+++ b/build.sh
@@ -21,12 +21,12 @@ __referenceassemblyroot=$__monoroot/lib/mono/xbuild-frameworks
 __monoversion=$(mono --version | grep "version 4.[1-9]")
 
 if [ $? -ne 0 ]; then
-    echo "Mono 4.1 or later is required to build corefx. Please see https://github.com/dotnet/corefx/wiki/Building-On-Unix for more details."
+    echo "Mono 4.1 or later is required to build corefx. Please see https://github.com/dotnet/corefx/blob/master/Documentation/linux-instructions.md for more details."
     exit 1
 fi
 
 if [ ! -e "$__referenceassemblyroot/.NETPortable" ]; then
-    echo "PCL reference assemblies not found. Please see https://github.com/dotnet/corefx/wiki/Building-On-Unix for more details."
+    echo "PCL reference assemblies not found. Please see https://github.com/dotnet/corefx/blob/master/Documentation/linux-instructions.md for more details."
     exit 1
 fi
 
@@ -37,7 +37,7 @@ __buildlog=$__scriptpath/msbuild.log
 if [ ! -e "$__nugetpath" ]; then
     which curl wget > /dev/null 2> /dev/null
     if [ $? -ne 0 -a $? -ne 1 ]; then
-        echo "cURL or wget is required to build corefx. Please see https://github.com/dotnet/corefx/wiki/Building-On-Unix for more details."
+        echo "cURL or wget is required to build corefx. Please see https://github.com/dotnet/corefx/blob/master/Documentation/linux-instructions.md for more details."
         exit 1
     fi
     echo "Restoring NuGet.exe..."