diff --git a/README.md b/README.md
index 2253d3b3..3330a1fa 100644
--- a/README.md
+++ b/README.md
@@ -36,108 +36,8 @@ Use this reference code to get started on building a [SCIM](https://docs.microso
|/ResourceTypes|**Retrieve supported resource types.**
The number and types of resources supported by each service provider can vary. (e.g. Service Provider A supports users while Service Provider B supports users and groups).|
|/ServiceProviderConfig|**Retrieve service provider's SCIM configuration**
The SCIM features supported by each service provider can vary. (e.g. Service Provider A supports Patch operations while Service Provider B supports Patch Operations and Schema Discovery).|
-## Prerequisites
-
-1. [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) (required)
-2. [.NET core 3.1 or above](https://dotnet.microsoft.com/download/dotnet-core/3.1) (required)
-3. [IIS](https://www.microsoft.com/download/details.aspx?id=48264) (required)
-4. [Postman](https://www.getpostman.com/downloads/) (optional)
-
-## Clone the repo and build your SCIM endpoint
-
-The solution is located in the ScimReferenceApi folder and can be built and run from VisualStudio locally or hosted in the cloud.
-
-#### Steps to run the solution locally
-1. Click **"Clone or download"** and click **"Open in Desktop"** OR copy the link.
-
-2. If you chose to copy the link, open Visual Studio and choose **"Clone or check out code**.
-
-3. Use the copied link from Github to make a local copy of all files.
-
-4. The Solution Explorer should open. Navigate to **Microsoft.SCIM.sln** view by double-clicking on it.
-
-5. Click **IIS Express** to execute. The project will launch as a web page with the local host URL.
-
-#### Steps to host the solution in the Azure
-1. Open Visual Studio and sign into the account that has access to your hosting resources.
-2. While in the **SCIMReference.sln** view, right-click the **SCIMReferenceApi** file in the Solution Explorer and select **"Publish"**.
-
- 
-
-3. Click create profile. Make sure **App Service** and **"Create new"** is selected.
-
- 
-
-4. Walk through the options in the dialog.
-5. Rename the app to a desired name of your choice. The name is used for both the app name and the SCIM Endpoint URL.
-
- 
-
-6. Select the resource group and plan you would like to use and click **"Publish"**.
-
-All the endpoints are are at the **{host}/scim/** directory and can be interacted with standard HTTP requests. The **/scim/** route can be modified in the **ControllerConstant.cs** file located in **AzureADProvisioningSCIMreference > ScimReferenceApi > Controllers**.
-
-## Authorization
-The SCIM standard leaves authentication and authorization relatively open. You could use cookies, basic authentication, TLS client authentication, or any of the other methods listed [here](https://tools.ietf.org/html/rfc7644#section-2). You should take into consideration security and industry best practices when choosing an authentication/authorization method. Avoid insecure methods such as username and password in favor of more secure methods such as OAuth. Azure AD supports long-lived bearer tokens (for gallery and non-gallery applications) as well as the OAuth authorization grant (for applications published in the app gallery). This reference code allows you to either turn authorization off to simplify testing, generate a bearer token, or bring your own bearer token.
-
-**Option 1**: Turn off authorization (this should only be used for testing)
-* Navigate to the **UsersController.cs** or **GroupController.cs** files located in **ScimReferenceApi > Controllers**.
2. Comment out the authorize command.
-
-**Option 2**: Get a bearer token signed by Microsoft security bearer (should only be used for testing, not in production)
-* Post to to the key endpoint with the string "SecureLogin" to retrieve a token. The token is valid for 120 minutes (the validity can be changed in the key controller).
-
-**Option 3**: Bring your own token
-* **Option 3a**: Generate your own token that matches the specifications of the reference code.
- * By default the issuer, audience, and signer must be "Microsoft.Security.Bearer"
- * These are defaults to get started testing quickly. They should not be relied on in production.
-* **Option 3b**: Generate your own token and update the specifications of the reference code to match your token.
- * Change the specifications in the configure service section of the startup.cs class.
- * Specify the authorization settings you would like to validate.
- * Generate a token on your own that matches those specifications.
-
-## Test your SCIM endpoint
-Provided below are test cases that you can use to ensure that your SCIM endpoint is compliant with the SCIM RFC.
-
-#### Postman instructions
-1. Download the [Postman client](https://www.getpostman.com/downloads/).
-2. Import the Postman collection by copying the link [here](https://aka.ms/ProvisioningPostman) and pasting it into Postman as shown below:
-
- 
-
-3. Create a Postman environment for testing by specifying the following variables below:
- * **If running the project locally**:
-
- |Variable|Value|
- |---|---|
- |Server|localhost|
- |Port|*The port you are using (e.g. **:44355**)|
- |API|scim|
-
- * **If hosting the endpoint in Azure**:
-
- |Variable|Value|
- |---|---|
- |Server|scimreferenceapi19.azurewebsites.net|
- |Port||
- |API|scim|
-
-4. Turn off SSL Cert verification by navigating to **File > Settings > General > SSL certificate verification**.
-
- 
-
-5. Ensure that you are authorized to make requests to the endpoint:
- * **Option 1**: Turn off authorization for your endpoint (this is fine for testing purposes, but there must be some form of authorization for apps being used by customers in production).
- * **Option 2**: POST to key endpoint to retrieve a token.
-
-6. Run your tests!
-
-#### Tests executed
-
-|Test|Description|
-|---|---|
-|CRUD operations on a Resource|Test that resources can be made, modified and deleted.|
-|Resource filtering|Test that specific resources are located and returned by filtered value (e.g. **?filters=DisplayName+eq+%22BobIsAmazing%22**).|
-|Attribute filtering|Test that specific attributes are located and returned (e.g. **?attributes=userName,emails**).|
+## Getting Started
+The `Microsoft.SystemForCrossDomainIdentityManagement` project contains the code base for building a SCIM API. The `Microsoft.SCIM.Sample` project is there as a sample for using the project. A step by step guide for starting up with the project can be found [here](docs/get-started.md)
## Navigating the reference code
@@ -160,16 +60,7 @@ This reference code was developed as a .Net core MVC web API for SCIM provisioni
* Turning a PATCH request into an operation with attributes pertaining to the value path.
* Defining the type of operation that can be used to apply changes to resource objects.
-## Common scenarios
-|Scenario|How-to|
-|---|---|
-|Enable or disable authorization|**Steps**
1. Navigate to the **UsersController.cs** or **GroupController.cs** files located in **ScimReferenceApi > Controllers**.
2. Comment or uncomment out the authorize command.|
-|Add additional filterable attributes|**Steps**
1. Navigate to the **FilterUsers.cs** or **FilterGroups.cs** files located in **ScimReferenceApi > Protocol**.
2. Update the method to include the attributes that you would like to support filtering for. |
-|Support additional user resource extensions|**Steps**
1. Copy the **EnterpriseUser.cs** file located in **ScimReferenceApi > Schemas**.
2. Rename the class to your custom extension name (e.g. customExtensionName.cs)
3. Update the schema to match the desired naming convention.
4. Repeat steps 1 - 3 with the **EnterpriseAttributes.cs** file (located in ScimReferenceApi > Schemas > Attributes) and update it with the attributes that you need.|
-
-## Contents
-
-
+### Contents
| File/folder | Description |
|-------------------|--------------------------------------------|
| `ScimRefrenceAPI` | Sample source code. |
@@ -180,6 +71,34 @@ This reference code was developed as a .Net core MVC web API for SCIM provisioni
| `README.md` | This README file. |
| `LICENSE` | The license for the sample. |
+## Common scenarios
+|Scenario|How-to|
+|---|---|
+|Enable or disable authorization|**Steps**
1. Navigate to the **UsersController.cs** or **GroupController.cs** files located in **ScimReferenceApi > Controllers**.
2. Comment or uncomment out the authorize command.|
+|Add additional filterable attributes|**Steps**
1. Navigate to the **FilterUsers.cs** or **FilterGroups.cs** files located in **ScimReferenceApi > Protocol**.
2. Update the method to include the attributes that you would like to support filtering for. |
+|Support additional user resource extensions|**Steps**
1. Copy the **EnterpriseUser.cs** file located in **ScimReferenceApi > Schemas**.
2. Rename the class to your custom extension name (e.g. customExtensionName.cs)
3. Update the schema to match the desired naming convention.
4. Repeat steps 1 - 3 with the **EnterpriseAttributes.cs** file (located in ScimReferenceApi > Schemas > Attributes) and update it with the attributes that you need.|
+
+## Authorization
+The SCIM standard leaves authentication and authorization relatively open. You could use cookies, basic authentication, TLS client authentication, or any of the other methods listed [here](https://tools.ietf.org/html/rfc7644#section-2). You should take into consideration security and industry best practices when choosing an authentication/authorization method. Avoid insecure methods such as username and password in favor of more secure methods such as OAuth. Azure AD supports long-lived bearer tokens (for gallery and non-gallery applications) as well as the OAuth authorization grant (for applications published in the app gallery). This reference code allows you to either turn authorization off to simplify testing, generate a bearer token, or bring your own bearer token.
+
+**Option 1**: Turn off authorization (this should only be used for testing)
+* Navigate to the **UsersController.cs** or **GroupController.cs** files located in **ScimReferenceApi > Controllers**.
2. Comment out the authorize command.
+
+**Option 2**: Get a bearer token signed by Microsoft security bearer (should only be used for testing, not in production)
+* Post to to the key endpoint with the string "SecureLogin" to retrieve a token. The token is valid for 120 minutes (the validity can be changed in the key controller).
+
+**Option 3**: Bring your own token
+* **Option 3a**: Generate your own token that matches the specifications of the reference code.
+ * By default the issuer, audience, and signer must be "Microsoft.Security.Bearer"
+ * These are defaults to get started testing quickly. They should not be relied on in production.
+* **Option 3b**: Generate your own token and update the specifications of the reference code to match your token.
+ * Change the specifications in the configure service section of the startup.cs class.
+ * Specify the authorization settings you would like to validate.
+ * Generate a token on your own that matches those specifications.
+
+Provided below are test cases that you can use to ensure that your SCIM endpoint is compliant with the SCIM RFC.
+
+
## Contributing to the reference code
This project welcomes contributions and suggestions! Like other open source contributions, you will need to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
diff --git a/Screenshots/CloneLinkVS-2.png b/docs/Screenshots/CloneLinkVS-2.png
similarity index 100%
rename from Screenshots/CloneLinkVS-2.png
rename to docs/Screenshots/CloneLinkVS-2.png
diff --git a/Screenshots/CloneLinkVS.png b/docs/Screenshots/CloneLinkVS.png
similarity index 100%
rename from Screenshots/CloneLinkVS.png
rename to docs/Screenshots/CloneLinkVS.png
diff --git a/Screenshots/CloneLinkVSO.png b/docs/Screenshots/CloneLinkVSO.png
similarity index 100%
rename from Screenshots/CloneLinkVSO.png
rename to docs/Screenshots/CloneLinkVSO.png
diff --git a/Screenshots/CloudPublish.png b/docs/Screenshots/CloudPublish.png
similarity index 100%
rename from Screenshots/CloudPublish.png
rename to docs/Screenshots/CloudPublish.png
diff --git a/Screenshots/CloudPublish2.png b/docs/Screenshots/CloudPublish2.png
similarity index 100%
rename from Screenshots/CloudPublish2.png
rename to docs/Screenshots/CloudPublish2.png
diff --git a/Screenshots/CloudPublish3.png b/docs/Screenshots/CloudPublish3.png
similarity index 100%
rename from Screenshots/CloudPublish3.png
rename to docs/Screenshots/CloudPublish3.png
diff --git a/Screenshots/Postman.png b/docs/Screenshots/Postman.png
similarity index 100%
rename from Screenshots/Postman.png
rename to docs/Screenshots/Postman.png
diff --git a/Screenshots/Postman2.png b/docs/Screenshots/Postman2.png
similarity index 100%
rename from Screenshots/Postman2.png
rename to docs/Screenshots/Postman2.png
diff --git a/Screenshots/SolutionExplorer.png b/docs/Screenshots/SolutionExplorer.png
similarity index 100%
rename from Screenshots/SolutionExplorer.png
rename to docs/Screenshots/SolutionExplorer.png
diff --git a/docs/get-started.md b/docs/get-started.md
new file mode 100644
index 00000000..6b34280b
--- /dev/null
+++ b/docs/get-started.md
@@ -0,0 +1,86 @@
+# Getting started with the solution
+## Prerequisites
+
+1. [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) (required)
+2. [.NET core 3.1 or above](https://dotnet.microsoft.com/download/dotnet-core/3.1) (required)
+3. [IIS](https://www.microsoft.com/download/details.aspx?id=48264) (required)
+4. [Postman](https://www.getpostman.com/downloads/) (optional)
+
+## Clone the repo and build your SCIM endpoint
+
+The solution is located in the ScimReferenceApi folder and can be built and run from VisualStudio locally or hosted in the cloud.
+
+#### Steps to run the solution locally
+1. Click **"Clone or download"** and click **"Open in Desktop"** OR copy the link.
+
+2. If you chose to copy the link, open Visual Studio and choose **"Clone or check out code**.
+
+3. Use the copied link from Github to make a local copy of all files.
+
+4. The Solution Explorer should open. Navigate to **Microsoft.SCIM.sln** view by double-clicking on it.
+
+5. Click **IIS Express** to execute. The project will launch as a web page with the local host URL.
+
+#### Steps to host the solution in the Azure
+1. Open Visual Studio and sign into the account that has access to your hosting resources.
+2. While in the **SCIMReference.sln** view, right-click the **SCIMReferenceApi** file in the Solution Explorer and select **"Publish"**.
+
+ 
+
+3. Click create profile. Make sure **App Service** and **"Create new"** is selected.
+
+ 
+
+4. Walk through the options in the dialog.
+5. Rename the app to a desired name of your choice. The name is used for both the app name and the SCIM Endpoint URL.
+
+ 
+
+6. Select the resource group and plan you would like to use and click **"Publish"**.
+
+All the endpoints are are at the **{host}/scim/** directory and can be interacted with standard HTTP requests. The **/scim/** route can be modified in the **ControllerConstant.cs** file located in **AzureADProvisioningSCIMreference > ScimReferenceApi > Controllers**.
+
+
+## Test your SCIM endpoint
+Provided below are test cases that you can use to ensure that your SCIM endpoint is compliant with the SCIM RFC.
+
+#### Postman instructions
+1. Download the [Postman client](https://www.getpostman.com/downloads/).
+2. Import the Postman collection by copying the link [here](https://aka.ms/ProvisioningPostman) and pasting it into Postman as shown below:
+
+ 
+
+3. Create a Postman environment for testing by specifying the following variables below:
+ * **If running the project locally**:
+
+ |Variable|Value|
+ |---|---|
+ |Server|localhost|
+ |Port|*The port you are using (e.g. **:44355**)|
+ |API|scim|
+
+ * **If hosting the endpoint in Azure**:
+
+ |Variable|Value|
+ |---|---|
+ |Server|scimreferenceapi19.azurewebsites.net|
+ |Port||
+ |API|scim|
+
+4. Turn off SSL Cert verification by navigating to **File > Settings > General > SSL certificate verification**.
+
+ 
+
+5. Ensure that you are authorized to make requests to the endpoint:
+ * **Option 1**: Turn off authorization for your endpoint (this is fine for testing purposes, but there must be some form of authorization for apps being used by customers in production).
+ * **Option 2**: POST to key endpoint to retrieve a token.
+
+6. Run your tests!
+
+#### Tests executed
+
+|Test|Description|
+|---|---|
+|CRUD operations on a Resource|Test that resources can be made, modified and deleted.|
+|Resource filtering|Test that specific resources are located and returned by filtered value (e.g. **?filters=DisplayName+eq+%22BobIsAmazing%22**).|
+|Attribute filtering|Test that specific attributes are located and returned (e.g. **?attributes=userName,emails**).|