added contributing guidelines, license, and updated README.md

3 files changed, 113 insertions, 4 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..e71622bc
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,43 @@
+# How to contribute
+
+Your feedback and contributions are greatly appreciated, and improve the quality of mdoc, monodoc, and related tools. Please read the following contribution guidelines to ensure a quick and timely review and acceptance of your patches.
+
+## Bug Reports and Feature Requests
+
+We love bug reports and feature requests! It is through feedback from our wonderful customers that we know how to prioritize our time. Please file issues and requests on [github issues](https://github.com/mono/api-doc-tools/issues/new). 
+
+For problems, please try to include a reproducible example … ideally in the form of an assembly (or compilable source code), and related script to reproduce the issue.
+
+For feature requests, please include all relevant details including input, output, and ideal file formats.
+
+## Contribution Workflow
+
+When contributing bug fixes and enhancements, please follow this workflow and guidelines.
+
+### Coding Standards
+
+This project is currently in transition. Historically, it has used the [Mono coding guidelines](http://www.mono-project.com/community/contributing/coding-guidelines/); and indeed, most of the code is currently still using this. 
+
+However, starting with the `MDocUpdater` class and related entities, we are changing to a new coding standard, based on the default formatting options available in _Visual Studio_ and _Visual Studio for Mac_. This is meant to simplify contributions, so that the IDE does not work against you without changes to the default format settings.
+
+Additionally, many areas of the code contain multiple classes in the same file. While there’s nothing wrong in general with this approach, going forward we will maintain each class in a separate `.cs` file, and organize functionality into better namespaces.
+
+If you are working in an area of the code that has transitioned to the new coding standard, please use that. If you are working with code that is still using the mono coding guidelines, and the change is small, just stick the existing format … otherwise, file a separate GitHub issue to request that the target code be reformatted. I would like to keep those formatting changes in a standalone commit (ie. no feature/functionality changes).
+
+### Commits
+
+This project tries to avoid chatty in-progress commits that are common during development. Once you’ve completed your development and are ready to move to the next stage of the contribution workflow, collapse your changes into as few feature-scoped commits as possible. Ideally if possible, every commit should pass all unit tests and be standalone.
+
+You can do so either by using an interactive rebase of your branch if you need multiple commits, or simply doing a soft reset `git reset origin/master —soft` … which will stage all of your changes and let you create a new single commit that contains all changes.
+
+### Tests
+
+Your commit should introduce no regressions. You can make sure to run all unit tests locally by using the [instructions here](https://github.com/mono/api-doc-tools#cli).
+
+### Pull Request
+
+Create a fork against the [api-doc-tools](https://github.com/mono/api-doc-tools/pulls) repository. As mentioned previously, all tests should pass, and the code will be reviewed, discussed, and merged from there. Please be ready to address any issues brought up during code review.
+
+## Legal
+
+This software is licensed under [The MIT License](LICENSE.md).
\ No newline at end of file
diff --git a/LICENSE.md b/LICENSE.md
new file mode 100644
index 00000000..262352aa
--- /dev/null
+++ b/LICENSE.md
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Xamarin, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/README.md b/README.md
index d68caa7b..37d4f50d 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,20 @@ This repository contains the source for Mono's [documentation toolchain](http://
 
 ## Compiling
 
+### Dependencies
+
+This repository uses submodules, so firstly, you have several options:
+
+- You can include all submodules when you initially clone: `git clone --recursive https://github.com/mono/api-doc-tools.git`
+- If you already have it local, you can use `git submodule update --init --recursive`
+- If you have all CLI dependencies (see below), you can `make prepare`
+
+### Visual Studio
+
+On windows, you can build and compile [`apidoctools.sln`](apidoctools.sln). And you can run unit tests if you have NUnit installed. If you use [Visual Studio for Mac](https://www.visualstudio.com/vs/visual-studio-mac/), you can use its built-in support for NUnit tests to also run tests.
+
 ### CLI
-If you've got `make` installed, you can run `make prepare all check`. The available targets are:
+If you've got `make` and `mono` installed, you can run `make prepare all check` to do a release build and run the full test suite (which for mdoc includes more than just the nunit tests). The available targets are:
 
 - `prepare`: initializes the submodules, and restores the nuget dependency of NUnit
 - `all`: compiles everything
@@ -17,6 +29,39 @@ You can also control some parameters from the command line:
 
 If you want to compile in debug mode: `make all CONFIGURATION=Debug`  
 
-### Visual Studio
-Once you run `make prepare all` at least once (to restore submodules), you can open the solution in 
-_Visual Studio_ to compile and debug.
+## Troubleshooting
+
+### WSL
+
+On the windows subsystem for linux, there is unfortunately a defect that causes difficulty making https calls, which in turn doesn't allow the `prepare` make target to complete (nuget fails). You will see an error that says:
+
+```
+Unable to load the service index for source https://api.nuget.org/v3/index.json.
+  An error occurred while sending the request
+  Error: ConnectFailure (Value does not fall within the expected range.)
+  Value does not fall within the expected range.
+```
+
+[this mono issue](https://github.com/mono/mono/pull/5003) Seems to indicate that the issue is resolved in newer insider builds of WSL.
+
+### Linux
+
+The following script will prepare, clone, and run a full build with tests of `mdoc` on an unbuntu docker container. 
+
+```
+apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF  
+echo "deb http://download.mono-project.com/repo/ubuntu trusty main" | tee /etc/apt/sources.list.d/mono-official.list
+
+apt-get update
+apt-get install git make mono-devel ca-certificates-mono wget nuget -s
+
+wget -q 'http://mxr.mozilla.org/seamonkey/source/security/nss/lib/ckfw/builtins/certdata.txt?raw=1' -O "/tmp/certdata.txt" 
+mozroots --import --ask-remove --file /tmp/certdata.txt
+
+
+git clone https://github.com/mono/api-doc-tools
+cd api-doc-tools
+make prepare all check
+```
+
+Please review [mono's installation guide](http://www.mono-project.com/download/#download-lin) if you are using a different flavor of linux.