Merge pull request #443 from microsoft/graph-azure-positioning

Clarifed the positioning of the MS Guidelines.

Author: markweitzel

Guidelines.md

@@ -1,3 +1,13 @@
+> # NOTICE TO READERS
+> 
+> ## **Guidance for Azure service teams**
+> Azure service teams should use the companion documents, [Azure REST API Guidelines](./azure/Guidelines.md) and [Considerations for Service Design](./azure/ConsiderationsForServiceDesign.md), when building or modifying their services. These documents provide a refined set of guidance targeted specifically for Azure services. For more information please refer to the [README](./azure/README.md) in the Azure folder.
+> 
+> ## **Guidance for Microsoft Graph service teams**
+> Graph service teams should reference the companion document, [Graph REST API Guidelines](./graph/GuidelinesGraph.md) when building or modifying their services. This document and the associated pattern catalog provides a refined set of guidance targeted specifically for Microsoft Graph services.
+
+---
+
 # Microsoft REST API Guidelines
 
 ## Microsoft REST API Guidelines Working Group
@@ -20,22 +30,13 @@ To provide the smoothest possible experience for developers on platforms followi
 
 This document establishes the guidelines Microsoft REST APIs SHOULD follow so RESTful interfaces are developed consistently.
 
-### **Guidance for Azure service teams**
-Azure service teams should use the companion documents, [Azure REST API Guidelines](./azure/Guidelines.md) and [Considerations for Service Design](./azure/ConsiderationsForServiceDesign.md), when building or modifying their services. These documents provide a refined set of guidance targeted specifically for Azure services. For more information please refer to the [README](./azure/README.md) in the Azure folder.
-
-### **Guidance for Microsoft Graph service teams**
-Graph service teams should reference the companion document, [Graph REST API Guidelines](./graph/GuidelinesGraph.md) when building or modifying their services. This document and the associated pattern catalog provides a refined set of guidance targeted specifically for Microsoft Graph services.
-
-
 ## 2. Table of contents
 <!-- TOC depthFrom:2 depthTo:4 orderedList:false updateOnSave:false withLinks:true -->
 
 - [Microsoft REST API Guidelines](#microsoft-rest-api-guidelines)
   - [Microsoft REST API Guidelines Working Group](#microsoft-rest-api-guidelines-working-group)
 - [Microsoft REST API Guidelines](#microsoft-rest-api-guidelines-1)
   - [1. Abstract](#1-abstract)
-    - [**Guidance for Azure service teams**](#guidance-for-azure-service-teams)
-    - [**Guidance for Microsoft Graph service teams**](#guidance-for-microsoft-graph-service-teams)
   - [2. Table of contents](#2-table-of-contents)
   - [3. Introduction](#3-introduction)
     - [3.1. Recommended reading](#31-recommended-reading)

README.md

@@ -1,17 +1,23 @@
-# Microsoft REST API Guidelines
+> # NOTICE TO READERS
+> 
+> ## Guidance for Azure service teams
+> Azure service teams should use companion documents, [Azure REST API Guidelines](./azure/Guidelines.md) and [Considerations for Service Design](./azure/ConsiderationsForServiceDesign.md), when building or modifying their services. These documents provide a refined set of guidance targeted specifically for Azure services. For more information please refer to the [README](./azure/README.md) in the Azure folder. 
+> 
+> ## Guidance for Microsoft Graph service teams
+> Microsoft Graph service teams should reference the companion document, [Graph REST API Guidelines](./graph/GuidelinesGraph.md) when building or modifying their services.
+>
+> In the process of building many of Microsoft's highest scale services, the Microsoft Graph team found the Microsoft API guidelines tremendously useful as a baseline. However, there are several areas where we need to provide more clarity on how developers should describe their APIs. The companion document, [Graph REST API Guidelines](./graph/GuidelinesGraph.md) is a set of amendments and clarifications for Microsoft Graph that act as further reading. Recognizing that two documents is a lot for a new API designer to absorb, our plan is to follow the approach Azure have taken and roll out guidelines for Microsoft Graph into a single consolidated document.
+
+---
+
+## Microsoft REST API Guidelines
 The [Microsoft REST API Guidelines](Guidelines.md) are Microsoft's internal company-wide REST API design guidelines.
 Teams at Microsoft typically reference this document when setting API design policy.
 They may additionally create documents specific to their team, adding further guidance or making adjustments as appropriate to their circumstances.
 
 We publish these guidelines here with the aim of fostering dialogue and learning in the API community at large.
 We further hope that these guidelines may encourage other organizations to create guidelines that are appropriate for them and in turn, if they are able, to publish theirs.
 
-### Guidance for Azure service teams
-Azure service teams should use companion documents, [Azure REST API Guidelines](./azure/Guidelines.md) and [Considerations for Service Design](./azure/ConsiderationsForServiceDesign.md), when building or modifying their services. These documents provide a refined set of guidance targeted specifically for Azure services. For more information please refer to the [README](./azure/README.md) in the Azure folder. 
-
-### Guidance for Microsoft Graph service teams
-Graph service teams should reference the companion document, [Graph REST API Guidelines](./graph/GuidelinesGraph.md) when building or modifying their services. This document and the associated pattern catalog provides a refined set of guidance targeted specifically for Microsoft Graph services.
-
 [![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)
 
 ## Code of Conduct