More markdown styling

azure/.markdownlint.json

@@ -0,0 +1,16 @@
+{
+  "default": true,
+  "MD012": {
+    "maximum": 2
+  },
+  "MD013": {
+    "line_length": 500
+  },
+  "MD022": false,
+  "MD031": false,
+  "MD032": false,
+  "MD033": {
+    "allowed_elements": [ "sup" ]
+  },
+  "MD036": false
+}

azure/ConsiderationsForServiceDesign.md

@@ -1,7 +1,9 @@
 ## Considerations for Service Design
+
 Great APIs make your service usable to customers. They are intuitive, naturally reflecting and communicating the underlying model and its behavior. They lend themselves easily to client library implementations in multiple programming languages. And they don't "get in the way" of the developer, by remaining stable and predictable, _especially over time_.
 
-This document provides Microsoft teams building Azure services with a set of guidelines that  help service teams build great APIs. The guidelines create APIs that are approachable, sustainable, and consistent across the Azure platform. We do this by applying a common set of patterns and web standards to the design and development of the API. For developers, a well defined and constructed API enables them to build fault-tolerant applications that are easy to maintain, support, and grow. For Azure service teams, the API is often the source of code generation enabling a broad audience of developers across multiple languages.
+This document provides Microsoft teams building Azure services with a set of guidelines that  help service teams build great APIs. The guidelines create APIs that are approachable, sustainable, and consistent across the Azure platform. We do this by applying a common set of patterns and web standards to the design and development of the API.
+For developers, a well defined and constructed API enables them to build fault-tolerant applications that are easy to maintain, support, and grow. For Azure service teams, the API is often the source of code generation enabling a broad audience of developers across multiple languages.
 
 Azure Service teams should engage the Azure HTTP/REST Stewardship Board early in the development lifecycle for guidance, discussion, and review of their API. In addition, it is good practice to perform a security review, especially if you are concerned about PII leakage, compliance with GDPR, or any other considerations relative to your situation.
 
@@ -17,7 +19,8 @@ It is critically important to design your service to avoid disrupting users as t
 *Note: Developing a new service requires the development of at least 1 (management plane) API and potentially one or more additional (data plane) APIs.  When reviewing v1 service APIs, we see common advice provided during the review.*
 
 A **management plane** API is implemented through the Azure Resource Manager (ARM) and is used to provision and control the operational state of resources.
-A **data plane** API is used by developers to implement applications. Occasionally, some operations are useful for provisioning/control and applications. In this case, the operation can appear in both APIs. Although, best practices and patterns described in this document apply to all HTTP/REST APIs, they are especially important for **data plane** services because it is the primary interface for developers using your service. The **management plane** APIs may have other preferred practices based on [the conventions of the Azure ARM](https://github.com/Azure/azure-resource-manager-rpc).
+A **data plane** API is used by developers to implement applications. Occasionally, some operations are useful for provisioning/control and applications. In this case, the operation can appear in both APIs.
+Although, best practices and patterns described in this document apply to all HTTP/REST APIs, they are especially important for **data plane** services because it is the primary interface for developers using your service. The **management plane** APIs may have other preferred practices based on [the conventions of the Azure ARM](https://github.com/Azure/azure-resource-manager-rpc).
 
 
 ### Start with the Developer Experience
@@ -30,12 +33,12 @@ Follow these practices to create clear names for your abstractions:
 - Pick one word/term out of a set of synonyms and stick to it.
 
 It is extremely difficult to create an elegant API that works well on top of a poorly designed service; the service team and customers will live with this pain for years to come. So, the service team should empathize with customers by:
- - Building apps that consume the API
- - Hold reviews and share what is learned with your team
- - Get customer feedback from API previews
- - Thinking about the code that a customer writes both before and after an HTTP operation
- - Initializing and reading from the data structures your service requires
- - Thinking about which errors are recoverable at runtime as opposed to indicating a bug in the customer code that must be fixed
+- Building apps that consume the API
+- Hold reviews and share what is learned with your team
+- Get customer feedback from API previews
+- Thinking about the code that a customer writes both before and after an HTTP operation
+- Initializing and reading from the data structures your service requires
+- Thinking about which errors are recoverable at runtime as opposed to indicating a bug in the customer code that must be fixed
 
 The whole purpose of a preview to address feedback by improving abstractions, naming, relationships, API operations, and so on. It is OK to make breaking changes during a preview to improve the experience now so that it is sustainable long term.
 
@@ -117,4 +120,5 @@ When engaging with the API REST Stewardship board, your working sessions will ge
 - Well formed - Do your services adhere to REST and Azure standards, e.g. proper return codes, use of headers.
 - Durable - Your APIs will grow and change over time and leveraging the common patterns described in this document will help you minimize your tech debt and move fast with confidence.
 
-It was once said that "all roads lead to Rome." For cloud services, the equivalent might be that "all 'roads' start with your API." That could not be more true than at Microsoft, where client libraries, documentation, and many other artifacts all originate from the fundamental way you choose to expose your service. With careful consideration at the outset of your development effort, the architectural stewardship of the API board, and the thoughtful application of these guidelines, you will be able to produce a consistent, well formed API that will delight our customers.
+It was once said that "all roads lead to Rome." For cloud services, the equivalent might be that "all 'roads' start with your API." That could not be more true than at Microsoft, where client libraries, documentation, and many other artifacts all originate from the fundamental way you choose to expose your service.
+With careful consideration at the outset of your development effort, the architectural stewardship of the API board, and the thoughtful application of these guidelines, you will be able to produce a consistent, well formed API that will delight our customers.